[haiku] Re: Documenting your package
- From: Ingo Weinhold <ingo_weinhold@xxxxxx>
- To: haiku@xxxxxxxxxxxxx
- Date: Sun, 03 Apr 2016 12:20:51 +0200
On 04/03/2016 12:13 AM, Pete Goodeve wrote:
One thing I've seen essentially no discussion of [though maybe
I missed it as usual...] is how and where to write the manual(s)
for an hpkg one has written. The current state actually seems
to be a bit of a mess.
Some apps which have their own folder in system/apps -- like Pe --
put the documentation in that folder. This seems reasonable,
but only applies to those organized like that.
The system/documentation folder doesn't seem to have much
organization at all. There are 'man' and 'info' subfolders, which
again is reasonable for that kind of doc. A couple of packages
('diskusage' and 'pdflib' on my system) have doc folders directly
under system/documentation, but they're the only ones.
They probably shouldn't do that.
The 'packages' subfolder holds the most, but this seems redundant,
as by definition anything in system/documentation must have come
from a package!
The name of the directory is inherited from the Unix (or Linux) world,
where it's usually .../share/doc/packages. It would be named the same in
a non-packaged installation location.
A couple of other installed packages (ImageMagick and libxslt)
have put their docs in system/data/docs.
That doesn't sound right either.
Was there any particular design behind all this, or has it "just growed"?
My personal preference would be to have everything in appropriately
named folders directly under system/documentation, so the user would
know where to look. Any objection to this?
The basic idea is that documentation/ itself contains mainly a few
directories that organize documentation by type (man, info, packages
(packages as a fallback for documentation that doesn't fit any former
category)), with a few additions of system level documentation. The
BeBook is apparently misplaced and should rather live in
develop/documentation/.
To sum it up:
* Documentation for a self-contained app can live in the app's directory.
* Documentation of a common type (man, info) goes into the respective
subdirectory of documentation/ (it has to for the respective tools to
find it).
* Development specific documentation goes into
develop/documentation/<package-name>/.
* Any other documentation goes into documentation/packages/<package-name>/.
Note that <package-name> is either the bare name of the packaged
software (not necessarily the actual name of the package) or, if
multiple versions of the software can be installed at the same time, the
name plus the discriminating part of the version (e.g. libfoo-1 or
libbar-1.4).
My immediate interest is that I have a command-line app that will
obviously go in .../bin. It has a README and an example that need
to be stashed somewhere, so I'm intending to do as i suggest above.
They should rather live in documentation/packages/<app-name>/.
CU, Ingo
Other related posts:
