Policy for documentation of ELPA

Policy for documentation of ELPA

[Evgeny M. Zubok]

Hi,

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?

Re: Policy for documentation of ELPA

[Stefan Monnier]

> 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.


        Stefan

Re: Policy for documentation of ELPA

[Evgeny M. Zubok]

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?

Re: Policy for documentation of ELPA

[Jambunathan K]

"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.

-- 

Re: Policy for documentation of ELPA

[Stefan Monnier]

> 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.

That sounds OK, yes.  Maybe the elpa/Makefile should handle Texinfo
fully automatically, tho an alternative would be for elpa/Makefile to
run a particular `make' target in each package dir, so every package can
provide a Makefile with the particular extra rules it needs.


        Stefan

Re: Policy for documentation of ELPA

[Chong Yidong]

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

> 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?

For packages developed in the GNU ELPA bzr repository, the texinfo file
should be in the same place as the sources, e.g. packages/FOO/doc/.  The
generated Info file should be in packages/FOO/dir, so that package.el
will add it to Info-directory-list.

I think Stefan's idea of optional per-package Makefiles is a good way to
handle this, and I'll look into implementing it.  For now, the manual
you have written could be added to the repository and manually converted
into Info.