Re: Policy for documentation of ELPA

[Jambunathan K <kjambunathan@gmail.com>]

"Evgeny M. Zubok" <evgeny.zubok@tochka.ru> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>>> I have written documentation (an initial version) for one of the ELPA
>>> package. The source is the texinfo file. I see that auctex provides the
>>> documentation as exported .info file along with Postscript and PDF in
>>> ./doc directory. Muse also provides the .info file. No package that
>>> provides source of documentation (texinfo files, PostScript diagrams and
>>> figures, etc). What is the current (if any) policy for documentation?
>>> Should the package also contain sources, just in case if someone want to
>>> improve the documentation?
>>
>> It should definitely contain the source (in this case the Texinfo) if at
>> all possible.
>
> And what about the documentation in compiled format? org-mode and muse
> have its own upstream development and they keep the documentation
> sources there. The developers commit only user-readable documentation
> into ELPA and they don't commit the texinfo. `debbugs' uses ELPA for
> development. So, we have no other option than to store texinfo file in
> ELPA. No problem. The main question is about the documentation in human
> readable format. ELPA contains the files as they will be installed at
> user side, right? Should I manually re-generate the final documentation
> every time I have made even the little change in texinfo file? Can I do
> it not very often? Where the documentation should arrive when the user
> installs the ELPA package?

I think you are suggesting that texi2pdf, texi2html be run on the texi
files and pdftex be run on the tex cheatsheets if any, automagically by
the ELPA infrastructure.

 Personally I think your suggestion is a very good idea and shifts the
burden away from the developer.

I think there is an opportuinity to further normalize the dir layout of
elpa tarballs (for eg, maintainers could insist that all doc files go
under ./doc etc etc)

If you are talking of doc files that are NOT DERIVED from texi files
then you can still include them under the directory of your own choosing
in the resulting tarballs.

ps: I am not much aware of the bzr version of GNU ELPA.

Jambunathan K.

--