Re: Emacs Mini Manual (PART 3) - CUSTOMIZING AND EXTENDING EMACS

[Emanuel Berg]

Javier <nospam@nospam.com> writes:

>> Yes, documentation on-screen is great in the man
>> page sense, the online Emacs help sense, when you
>> want to know some part of the interface. If you do
>> Elisp for some time, and then switch to C, you feel
>> like an idiot having to Google stuff because the
>> interface isn't available (though some of the C is
>> in the manpages). But there is actually nothing that
>> stops anyone from writing C (interface)
>> documentation that would work more or less like the
>> Elisp one.
>
> It would be an interesting project to convert those
> documents to texinfo format.  With Python it is
> possible to convert the documentation (sphinx doc
> generator) of Python and its libraries to texinfo,
> and documentation can be gerated automatically for
> any python project to texinfo.

Yeah? What documents?

You can get the Emacs manual in texinfo here:

http://www.gnu.org/software/emacs/manual/texi/emacs.texi.tar.gz

I take it that's what you get with the info command,
only not markuped, of course.

In the the on-line help, the docstrings associated to
defuns and variables, they aren't that advanced.

The arguments should be mentioned, in caps - probably
to make them visible - they get the
`help-argument-name' face. In the source, it looks kind
of strange with arguments not the same case in the
docstring as everywhere else. But in help-mode the
parameters in the definition gets uppercased, so there
it's consistent.

All parameters should be mentioned, in the docstring,
and there should be two spaces after a full stop. This
is something I learned from `checkdoc-current-buffer',
check out this example - it should tell you arg2 isn't
mentioned (apart from some other library related stuff
that doesn't apply). But in reality far from everything
is documented and sometimes it is, but not the
parameters...

(defun test-param-doc (arg1 arg2)
  "ARG1 does this.  Also check out `find-file'."
  (interactive)
  nil) ; eval here

(checkdoc-current-buffer t) ; and here

Some hypertext is possible with `this' method - if
there actually is such a function or whatever, that get
hypertexted and the `button' face in help-mode.

-- 
underground experts united