hideshow docstring in elisp or common lisp code

hideshow docstring in elisp or common lisp code

[Mirko Vukovic]

Hello,

I would like to hide/show docstrings of my common lisp code.

Has that been defined in some hideshow package?

If not I'll give it a shot, initially for defuns.

Thank you,

Mirko

Re: hideshow docstring in elisp or common lisp code

[Michael Heerdegen]

Mirko Vukovic <mirko.vukovic@gmail.com> writes:

> I would like to hide/show docstrings of my common lisp code.
>
> Has that been defined in some hideshow package?
>
> If not I'll give it a shot, initially for defuns.

AFAIK no, hideshow is only about blocks.  However, you could try to
teach hideshow that it should handle strings as blocks.  Can be done by
simply customizing hs-special-modes-alist.  It isn't fun to do this,
however, since it's not easy to do it in a way that doesn't totally
confuse hideshow.

Michael.

Re: hideshow docstring in elisp or common lisp code

[Andreas Röhler]

On 09.11.2018 03:12, Michael Heerdegen wrote:
> Mirko Vukovic <mirko.vukovic@gmail.com> writes:
> 
>> I would like to hide/show docstrings of my common lisp code.
>>
>> Has that been defined in some hideshow package?
>>
>> If not I'll give it a shot, initially for defuns.
> 
> AFAIK no, hideshow is only about blocks.  However, you could try to
> teach hideshow that it should handle strings as blocks.  Can be done by
> simply customizing hs-special-modes-alist.  It isn't fun to do this,
> however, since it's not easy to do it in a way that doesn't totally
> confuse hideshow.
> 
> Michael.
> 


External thing-at-point-utils.el provides

(defun ar-hide-string-atpt (&optional arg)
   "Hides STRING at point. "
   (interactive "P")
   (ar-th-hide 'string))

(defun ar-show-string-atpt (&optional arg)
   "Shows hidden STRING at point. "
   (interactive "P")
   (ar-th-show 'string))

Remains to write some function traveling the buffer and picking 
docstring-sections

https://github.com/andreas-roehler/thing-at-point-utils

RE: hideshow docstring in elisp or common lisp code

[Drew Adams]

> I would like to hide/show docstrings of my common lisp
> code.  Has that been defined in some hideshow package?
> If not I'll give it a shot, initially for defuns.

This is all you need to do, but you need these 3 libraries:
`zones.el', `highlight.el', `isearch-prop.el'.

1. Create zones of all of the doc strings, fontifying
   the full buffer.

   `M-x zz-create-face-zones font-lock-doc-face'

2. Toggle invisibility of the zones.

   `M-x isearchp-toggle-zones-invisible'

Step 1 fontifies the full buffer, then creates a
sequence of non-overlapping buffer zones for the
doc strings. Step 2 makes the zones invisible.
Use the same toggle command, to make them visible.

I defined this stuff for Elisp code, but I imagine
it works also for Common Lisp code.

You can get all 3 libraries from Emacs Wiki.

After the latest version of `zones.el' gets added
to GNU ELPA (soon, I think) you can get it (but not
the others) also from GNU ELPA.

https://www.emacswiki.org/emacs?action=elisp-area;context=0

RE: hideshow docstring in elisp or common lisp code

[Drew Adams]

You also have similar command
`isearchp-toggle-zone/anti-zone-visibility', which
toggles between showing only the zones (in this case
only the doc strings) and showing only the anti-zones
(in this case all but the doc strings).

Related commands:
`isearchp-make(-anti)-zones-visible',
`isearchp-make(-anti)-zones-invisible', and
`isearchp-toggle-anti-zones-invisible'.
And `isearchp-add-prop-to-other-prop-zones' and
`isearchp-put-prop-on-zones', which you can use to
add a text property such as `invisible' to zones.

And commands to search just within zones:
`isearchp-zones-(backward|forward)(-regexp)'.

By default, the anti-zones are dimmed a bit while
you search, to help the zones to stand out.  This is
controlled by options `isearchp-dimming-color' and
`isearchp-dim-outside-search-area-flag'.  The latter
option (thus the dimming) can be toggled by `C-M-S-d'
during Isearch.

And command `isearchp-toggle-complementing-domain'
flips whether to search the zones or the anti-zones.
It's bound to `C-M-~' during Isearch.  So, for
example, having defined doc strings as the zones,
you can search either doc strings or everything but
doc strings, just by hitting `C-M-~'.

All of the commands just mentioned are from library
`isearch-prop.el'.  But the ones specifically for
use with zones require also library `zones.el'.

Re: hideshow docstring in elisp or common lisp code

[Emanuel Berg]

Mirko Vukovic wrote:

> I would like to hide/show docstrings of my
> common lisp code.

Sorry for a non-answer, but why do you want to
do that? Instead, practice to write really
short and to-the-point instructions :)

There are formal rules, which are good to stick
to. Probably you are aware of them, and the
facilities to formally check the formalities,
but I tell you/everyone else anyway how to do
it:

    (defun check-package-style ()
      (interactive)
      (checkdoc-current-buffer t) ; TAKE-NOTES
      (message "Style check done.") )

Good luck!

-- 
underground experts united
http://user.it.uu.se/~embe8573

Re: hideshow docstring in elisp or common lisp code

[Mirko]

On Tuesday, November 6, 2018 at 2:05:17 PM UTC-5, Emanuel Berg wrote:
> Mirko Vukovic wrote:
> 
> > I would like to hide/show docstrings of my
> > common lisp code.
> 
> Sorry for a non-answer, but why do you want to
> do that? Instead, practice to write really
> short and to-the-point instructions :)
> 
> There are formal rules, which are good to stick
> to. Probably you are aware of them, and the
> facilities to formally check the formalities,
> but I tell you/everyone else anyway how to do
> it:
> 
>     (defun check-package-style ()
>       (interactive)
>       (checkdoc-current-buffer t) ; TAKE-NOTES
>       (message "Style check done.") )
> 
> Good luck!
> 
> -- 
> underground experts united
> http://user.it.uu.se/~embe8573

Emanuel,

First thanks for pointing to checkdoc.  I was not
aware of it.

My intent is to keep the function's documentation
close to the function itself.  

For my Common Lisp code I follow the layout used in
the official documentation (the Hyperspec), which
while verbose, starts with a single line brief
explaining the function.  Hideshow on that would work
very nicely on that convention.

One benefit (for me) is the documentation generator 
(HeLambdaP) that parses the lisp file and the docstring,
and generates the html documentation straight from the
docstring.

To summarize:
- keeping documentation close to the code makes 
  maintenance easy
- Following hyperspec convention allows for generation
  of html documentation.

Mirko