bug#67499: [PATCH] Add use cases of (fn) documentation facility.

[Jeremy Bryant]

Tags: patch


I have written a proposed addition to the Elisp manual.  In now-closed
bug 66928, there was a discussion related to the use of \(fn) in doc
strings, and I have drafted some examples to explain how this facility
could be used.  The addition is presented as @ifnottex... in order to
reduce the cost of the printed manual.

Feedback welcome on draft before I refine further, on conventions, section of
manual, style etc.





> Interesting, thank you 
> Perhaps it would be of interest to add some text to the elisp manual in
> (elisp) Function Documentation

> Are there any conventions for manual additions?
> in particular to keep the number of printed pages limited is there a way
> to say 'don't print this node'?

> thanks
> Jeremy


> Stefan Monnier <monnier@iro.umontreal.ca> writes:

> >> One question, the elisp manual mentions that the \(fn ARGLIST) facility
> >> is particularly useful for macros.
> >>
> >> Why would we use this for defuns?
> >
> > We use it for some defuns where ELisp's arglist functionality is not
> > refined enough to express the intention of the programmer.
> > For example, the "real" arglist may be
> >
> >     name args &optional docstring &rest body
> >
> > but the intended arglist is
> >
> >     name args [docstring] &rest body
> >
> > i.e. if `docstring` is not a string it's taken as the first instruction
> > of `body`.
> >
> >
> >         Stefan

0001-Add-use-cases-of-fn-documentation-facility.patch
Description: Text Data