Documentation about elisp code

Documentation about elisp code

[steve-humphreys]

What would be a good strategy to use for displaying some documentation
regarding some elisp code I have written.

Naturally, I included documentation strings in my defuns.  But there
is no information about learning the functionalities provided by my code.
.

Re: Documentation about elisp code

[steve-humphreys]

Is there a way to call the documentation of another defun from the
in the doc-string using some sort of link?




> Sent: Sunday, May 02, 2021 at 4:34 PM
> From: steve-humphreys@gmx.com
> To: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> Subject: Documentation about elisp code
>
>
> What would be a good strategy to use for displaying some documentation
> regarding some elisp code I have written.
>
> Naturally, I included documentation strings in my defuns.  But there
> is no information about learning the functionalities provided by my code.
> .
>
>
>
>
>
>
>

Re: Documentation about elisp code

[Jean Louis]

* steve-humphreys@gmx.com <steve-humphreys@gmx.com> [2021-05-02 07:34]:
> What would be a good strategy to use for displaying some documentation
> regarding some elisp code I have written.
> 
> Naturally, I included documentation strings in my defuns.  But there
> is no information about learning the functionalities provided by my code.

I recommend reading about: (info "(elisp) Packaging")

There are few ways to document it:

- document it inline in documentation strings and if necessary in the
  Commentary section inside of a package;

- or create multi file package and use either README or info file or
  other file to document it; best would be info if documentation is
  important;



-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/
https://rms-support-letter.github.io/

Re: Documentation about elisp code

[steve-humphreys]

I have coded so much stuff that I hardly remember what capabilities
exist.  Would really like to access an abbreviated documentation
inside emacs, whilst I am hacking at things.  Using manual online,
or a pdf (etc) is very  inconvenient.

I quite like the idea of using something similar to

(info "(elisp) Packaging")

For instance

(info "(myelisp) Topic")

Is there a way for such functionality?



> Sent: Sunday, May 02, 2021 at 5:31 PM
> From: "Jean Louis" <bugs@gnu.support>
> To: steve-humphreys@gmx.com
> Cc: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: Documentation about elisp code
>
> * steve-humphreys@gmx.com <steve-humphreys@gmx.com> [2021-05-02 07:34]:
> > What would be a good strategy to use for displaying some documentation
> > regarding some elisp code I have written.
> >
> > Naturally, I included documentation strings in my defuns.  But there
> > is no information about learning the functionalities provided by my code.
>
> I recommend reading about: (info "(elisp) Packaging")
>
> There are few ways to document it:
>
> - document it inline in documentation strings and if necessary in the
>   Commentary section inside of a package;
>
> - or create multi file package and use either README or info file or
>   other file to document it; best would be info if documentation is
>   important;
>
>
>
> --
> Jean
>
> Take action in Free Software Foundation campaigns:
> https://www.fsf.org/campaigns
>
> Sign an open letter in support of Richard M. Stallman
> https://stallmansupport.org/
> https://rms-support-letter.github.io/
>
>
>

Re: Documentation about elisp code

[Tassilo Horn]

steve-humphreys@gmx.com writes:

> Is there a way to call the documentation of another defun from the
> in the doc-string using some sort of link?

When your docstring contains `some-other-function-or-var' (with this
quoting), it'll be a clickable link in the *Help* buffer.  And `C-h f'
and `C-h v' will also suggest that as default when point is on that
symbol.

Bye,
Tassilo

Re: Documentation about elisp code

[Eli Zaretskii]

> Date: Sun, 2 May 2021 08:31:10 +0300
> From: Jean Louis <bugs@gnu.support>
> Cc: Help Gnu Emacs <help-gnu-emacs@gnu.org>
> 
> There are few ways to document it:
> 
> - document it inline in documentation strings and if necessary in the
>   Commentary section inside of a package;
> 
> - or create multi file package and use either README or info file or
>   other file to document it; best would be info if documentation is
>   important;

There's also the Commentary section of a .el file and the
corresponding "C-h P" command.

Re: Documentation about elisp code

[steve-humphreys]

Have tried your suggestion, but the funtion is not clickable

(defun guide ()
  "`guidance-ediff'"

  (message "guide") )


> Sent: Sunday, May 02, 2021 at 6:58 PM
> From: "Tassilo Horn" <tsdh@gnu.org>
> To: steve-humphreys@gmx.com
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Documentation about elisp code
>
> steve-humphreys@gmx.com writes:
>
> > Is there a way to call the documentation of another defun from the
> > in the doc-string using some sort of link?
>
> When your docstring contains `some-other-function-or-var' (with this
> quoting), it'll be a clickable link in the *Help* buffer.  And `C-h f'
> and `C-h v' will also suggest that as default when point is on that
> symbol.
>
> Bye,
> Tassilo
>
>

Re: Documentation about elisp code

[Tassilo Horn]

steve-humphreys@gmx.com writes:

> Have tried your suggestion, but the funtion is not clickable
>
> (defun guide ()
>   "`guidance-ediff'"
>
>   (message "guide") )

It it defined?  It will only be clickable if it is a function which is
actually defined when you view the docs.  For example, when evaluating
those two functions, they are linked in *Help* and I can switch between
them by following the link:

--8<---------------cut here---------------start------------->8---
(defun th/foo ()
  "See `th/bar'."
  nil)

(defun th/bar ()
  "See `th/foo'."
  nil)
--8<---------------cut here---------------end--------------->8---

Bye,
Tassilo

Re: Documentation about elisp code

[steve-humphreys]

Yes, I defined it.  Have got it to work now, because earlier I had forgotten
to load the file.

Thank you.

> Sent: Sunday, May 02, 2021 at 8:21 PM
> From: "Tassilo Horn" <tsdh@gnu.org>
> To: steve-humphreys@gmx.com
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Documentation about elisp code
>
> steve-humphreys@gmx.com writes:
>
> > Have tried your suggestion, but the funtion is not clickable
> >
> > (defun guide ()
> >   "`guidance-ediff'"
> >
> >   (message "guide") )
>
> It it defined?  It will only be clickable if it is a function which is
> actually defined when you view the docs.  For example, when evaluating
> those two functions, they are linked in *Help* and I can switch between
> them by following the link:
>
> --8<---------------cut here---------------start------------->8---
> (defun th/foo ()
>   "See `th/bar'."
>   nil)
>
> (defun th/bar ()
>   "See `th/foo'."
>   nil)
> --8<---------------cut here---------------end--------------->8---
>
> Bye,
> Tassilo
>

Re: Documentation about elisp code

[Nikolay Kudryavtsev]

(info "(myelisp) Topic") just finds "Topic" in "myelisp" info manual. So if you write that manual and get it to install for the user(generally done by distributing your code through package.el) it would work.

Apart from everything suggested previously there's also an option of writing a custom help command, which user can quickly open with a hotkey. Some beefier pacakges do that, like Helm and Icicles.

Re: Documentation about elisp code

[steve-humphreys]

> Sent: Sunday, May 02, 2021 at 9:08 PM
> From: "Nikolay Kudryavtsev" <nikolay.kudryavtsev@gmail.com>
> To: steve-humphreys@gmx.com, "Jean Louis" <bugs@gnu.support>
> Cc: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: Documentation about elisp code
>
> (info "(myelisp) Topic") just finds "Topic" in "myelisp" info manual. So if you write that manual and get it to install for the user(generally done by distributing your code through package.el) it would work.
>
> Apart from everything suggested previously there's also an option of writing a custom help command, which user can quickly open with a hotkey. Some beefier pacakges do that, like Helm and Icicles.

Thanks, I am checking helm.  Thanks for the hints.

Re: Documentation about elisp code

[steve-humphreys]

Have made a defvar and want to output the string in message.
Getting into difficulties doing that.

(defvar guidance-message
  "* guidance

C-h f flight"

(defun guidance ()
   "todo"

   (message guidance-message) )

(guidance)



> Sent: Sunday, May 02, 2021 at 8:21 PM
> From: "Tassilo Horn" <tsdh@gnu.org>
> To: steve-humphreys@gmx.com
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Documentation about elisp code
>
> steve-humphreys@gmx.com writes:
>
> > Have tried your suggestion, but the funtion is not clickable
> >
> > (defun guide ()
> >   "`guidance-ediff'"
> >
> >   (message "guide") )
>
> It it defined?  It will only be clickable if it is a function which is
> actually defined when you view the docs.  For example, when evaluating
> those two functions, they are linked in *Help* and I can switch between
> them by following the link:
>
> --8<---------------cut here---------------start------------->8---
> (defun th/foo ()
>   "See `th/bar'."
>   nil)
>
> (defun th/bar ()
>   "See `th/foo'."
>   nil)
> --8<---------------cut here---------------end--------------->8---
>
> Bye,
> Tassilo
>

Re: Documentation about elisp code

[tomas]

[-- Attachment #1: Type: text/plain, Size: 562 bytes --]

On Sun, May 02, 2021 at 12:25:14PM +0200, steve-humphreys@gmx.com wrote:
> Have made a defvar and want to output the string in message.
> Getting into difficulties doing that.
> 
> (defvar guidance-message
>   "* guidance
> 
> C-h f flight"

There is a closing parenthesis missing here.

> (defun guidance ()
>    "todo"
> 
>    (message guidance-message) )
> 
> (guidance)

Besides... you could help us help you better by actually
describing your difficulties. Just "Getting into difficulties
doing that" is... difficult :)

Cheers
 - t

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: Documentation about elisp code

[steve-humphreys]

> Sent: Sunday, May 02, 2021 at 10:40 PM
> From: tomas@tuxteam.de
> To: steve-humphreys@gmx.com
> Cc: "Tassilo Horn" <tsdh@gnu.org>, help-gnu-emacs@gnu.org
> Subject: Re: Documentation about elisp code
>
> On Sun, May 02, 2021 at 12:25:14PM +0200, steve-humphreys@gmx.com wrote:
> > Have made a defvar and want to output the string in message.
> > Getting into difficulties doing that.
> >
> > (defvar guidance-message
> >   "* guidance
> >
> > C-h f flight"
>
> There is a closing parenthesis missing here.
>
> > (defun guidance ()
> >    "todo"
> >
> >    (message guidance-message) )
> >
> > (guidance)
>
> Besides... you could help us help you better by actually
> describing your difficulties. Just "Getting into difficulties
> doing that" is... difficult :)

You are right.  I found a missing closing parenthesis.  Have written
a rudimentary message about some help resources about some code I have
written.  Currently I am using the *Messages* buffer.  I would like to
use a special buffer for my tools, but do not have experience doing that.


> Cheers
>  - t
>

Re: Documentation about elisp code

[Emanuel Berg via Users list for the GNU Emacs text editor]

steve-humphreys wrote:

> You are right. I found a missing closing parenthesis.
> Have written a rudimentary message about some help resources
> about some code I have written. Currently I am using the
> *Messages* buffer. I would like to use a special buffer for
> my tools, but do not have experience doing that.

If you are doing an Elisp package byte-compile/improve until
there are no error messages, then do this [1] to look for
docstrings and other issues you might have overlooked, when OK
byte-compile again and all is done.

If you want your own interactive (online) help, sure, you can
have your own buffer for that, see how it is done for example
in this program [2]

What kind of program are you writing BTW? :O

[1]

(require 'checkdoc)

(setq checkdoc-permit-comma-termination-flag t)

(defun check-package-style ()
  (interactive)
  (let ((msg "Style check..."))
    (message msg)
    (checkdoc-current-buffer t) ; TAKE-NOTES
    (message "%sdone" msg) ))
(defalias 'check-style #'check-package-style)

https://dataswamp.org/~incal/emacs-init/ide/elisp.el

[2]

(defun print-roll-outs (chainrings sprockets bsd tire)
  (let ((out-buffer (get-buffer-create "*gears*")))
    (with-current-buffer out-buffer
      (goto-char (point-max))
      (print-intro-data chainrings sprockets bsd tire)
      (let ((ros (all-roll-outs chainrings sprockets bsd tire)))
        (cl-loop for ro in ros do
                 (let ((c (   car   ro))
                       (s (   cadr  ro))
                       (r (cl-caddr ro)))
                   (insert (format "% 9d% 14d% 15.0f\n" c s r)) ))))
    (pop-to-buffer out-buffer) ))

https://dataswamp.org/~incal/emacs-init/bike.el

-- 
underground experts united
https://dataswamp.org/~incal

Re: Documentation about elisp code

[Emanuel Berg via Users list for the GNU Emacs text editor]

steve-humphreys wrote:

> For instance
>
> (info "(myelisp) Topic")
>
> Is there a way for such functionality?

It is already there :)

You just have to write info-formatted documentation and put it
in the right place.

Again I ask what exactly it is you are writing because this
sounds like overkill for most projects. Can be interesting to
do all the same, of course...

-- 
underground experts united
https://dataswamp.org/~incal

RE: [External] : Re: Documentation about elisp code

[Drew Adams]

> Is there a way to call the documentation of another defun from the
> in the doc-string using some sort of link?

Yes.  Just do the following in your doc string:

1. Put the function or command (or variable or option)
   name between ` and ' in your doc string.  E.g.,
   `foobar'.

2. Put the word "function" or "command" (or "variable"
   or "option") immediately before the text of #1 in
   your doc string.  E.g., "...function `foobar'...".

Example:

(defun tata ()
  "This is tata.
And here is a link to function `forward-char'."
  42)

Programmatically, the link is created by a function
such as `help-insert-xref-button', to which you pass
the link-text string and a button type (and possibly
other args).  You can create a new button type using
macro `define-button-type'.

For the definition of `help-insert-xref-button',
examples of its use, and examples of defining button
types, see standard library `help-mode.el'.