Re: Spell checking of the commentary section by checkdoc.el.

[Oliver Scholz]

Although I very much prefer a lightweight markup, I am not religious
on that issue. That is, when Richard gives his o.k., I'd like to offer
to work on it, even if you decide to go for texinfo directly. [After I
am done with the fontset-customisation stuff, which will be in about 2
weeks I think. I am rather busy at the moment.]

"Stefan Monnier" <monnier+gnu/emacs/address@hidden> writes:

>> My preference for a Wiki-style markup is based on the assumption that
>> only a small subset of Texinfo is needed here and that designing the
>> markup and implementing the code to convert it is straightforward. I
>> may be wrong with either of these two assumptions, of course, but I
>> don't see it yet. As for the benefit of having the "Info:" section
>> look like plain ascii: well, your mileage varies, obviously. :-)
>
> The question to me is not whether "the full Texinfo" is needed
> but whether it hurts and I think the only way it can hurt is if
> it makes the text more difficult to write/read/maintain, so clearly
> the crux of the matter is the variation in mileage.

I prefer the "let it look like plain ASCII formatting" not so much for
the sake of better maintainability of the documentation texts. I doubt
that it will make much of a difference ín this regard. But I think
that a `finder-commentary' or `finder-by-keyword' on steroids should
provide a means to let small libraries hook into this new "Emacs
documentation system for small libraries". Like they already have a
means to hook into the "Emacs customisation system". That is: as soon
as a package in site-lisp is `require'd its "Info:" section should be
available in the "documentation system for small libraries".

Currently for small libraries the commentary section at the beginning
of the file is typically the most important documentation for end
users. I suspect that package authors that are concerned about
portability between different versions of Emacs and XEmacs are more
likely to cater for the "finder-commentary" on steroids, if it doesn't
imply that their users on other versions of Emacs/XEmacs are forced to
read the texinfo code. This is all just IMHO, of course. It's hard to
make guesses at the motivations and intentions of other's, but it
seems plausible to me.

[...]
>> What I have in mind is to generate the info manual on the fly:
[...]

> That would be one use (basically a `finder-commentary' on steroids).
> Another would be to generate actual info files and make them
> available in info for browsing:
>
>    C-h i m locally installed emacs packages RET m rmime RET
> or
>    C-h i m emacs RET m other bundled packages RET m smerge RET

Yes, I think this is a Good Thing. I also think that it should be
handled that way, even if Emacs generates the info pages on the
fly. That is, `info' should automatically add a menu entry that is
special: instead of visiting an existing info file, selecting this
menu entry triggers the generation of the pages. This is better than
putting it (only) on `C-h p', because it keeps similiar kinds of
documentation at the same place.

I prefer auto-generation on the fly to generation of actual info files
(presumably at the time when Emacs is compiled), because of the reason
mentioned above. For the sake of extensibility, I would like to invent
a way that allows packages distributed outside of Emacs to add their
documentation to this special info-subsystem.

[...]
> Another would be for HTML versions of the docs, such as on the
> home page of the author where he distributes the package.
>
> Being able to print it (nicely) is also a plus.
> All in all, I'd want to go through Texinfo even if we designed a
> special purpose d super-lightweight markup.

I agree.

> The potentially positive thing about a new markup is that we might be
> able to get good quality Texinfo output from a very lightweight markup
> because we get to look at the attached code to see what is what.
> But that'll require more work.
[...]

I don't understand what you mean here, I'm afraid.

    Oliver
-- 
28 Floréal an 211 de la Révolution
Liberté, Egalité, Fraternité!