Re: document registration policy needing to be written
## Nachricht vom 11.04.98 weitergeleitet
## Ursprung : doc-debian # lists.debian.org@243:9000/0
## Ersteller: Marco Budde@243:1000/1.15
Am 11.04.98 schrieb apharris # burrito.onshore.com ...
Moin Adam!
APH> 'doc-base' provides a single interface for package maintainer to use
APH> to register files with both systems. This is doc-base/hamm's only
APH> real function at this point.
I think it#s not a good idea to have two parsers like that:
0.) package calls doc-base for registration
1.) doc-base reads file
2.) produces .dhelp/dwww file
3.) runs dwww | dhelp
I think it would be better to have something like that:
1.) package calls a wrapper script for registration
2.) wrapper script calls the installed system:
for example dhelp or dwww or dhelp and dwww.
The package maintainers could use something like my dhelp2dwww or we add
dhelp support to dwww. Jim, if you need help, please email me.
APH> files. In that case, doc-base's install-docs system will be
APH> useless, in fact, creating a new document control file format
APH> without any additional purpose.
That#s right. Maybe we need to improve the .dhelp format? Do we need other
features? Maybe we should change the support for documents in foreign
languages.
At the moment, dhelp uses something like
<directory>de/HOWTO
Maybe it#s better to use something like that
<directory>HOWTO
<lang>de
Then it would be possible, that the system admin deletes non needed
languages from the index.
APH> The most recent version of dhelp includes a script to create dwww
APH> files based on .dhelp files.
And there#s a new script, that creates .dhelp, .dwww-index, and index.html
from sgml-tools documents. I#m using this for my doc-linux-* packages.
APH> could be made 'Required' or at least reasonably standard so that
APH> packages can register packages early on.
Well, my dhelp has got a size of 30 KB :). I would suggest the following:
1.) We add .dhelp support to .dwww
(this should be very easy)
2.) We add new tags to .dhelp, if we need news tags.
3.) We use the same section names in all packages
I thing, we don#t need doc-base for the registration. We could use doc-
base for the documentation format conversion (sgml -> ps, info, etc.). But
still thing, that the maintainer should offer the documents in different
formats.
APH> * consider file naming and placment. 'doc-base' uses
APH> /usr/share/doc-base/<pkg>; dhelp uses /usr/doc/<package>/.dhelp.
APH> In a way it's better to have files in /usr/share/doc-base or
APH> some such, since then there's a single file location for
APH> document control files
But where#s the advantage of /usr/share? For example for a package
maintainer my solution is better, because you don#t have to create
/usr/share/doc-base. And you can use relative paths with my solution. For
example you could move the documents to /usr/local/doc.
And you can use my solution in a simple tar file.
APH> * file format should be standardized, we should whip up a DTD and
APH> make it true SGML; this will assist in format validation and
APH> standardize file parsing
No, dhelp will never use a DTD! The goal of dhelp is to provide a small
and fast tool. I don#t like depencies to a sgml parser or to Perl. If you
use a DTD and your package uses Priority: standard, you have got a
problem.
APH> * add fields to register document type (ASCII, HTML, etc.) and
APH> language
That#s a good idea. Should we use <filetype> and use HTML as standard?
APH> * adopt the menu hierarchy as a standard documentation hierarchy (de
APH> facto; make it official)
Why? Let us talk about that. dhelp uses the structure of our ftp server.
And we have already translations to several languages.
APH> * Could document registration could be 'execution free', i.e., all
APH> we require is a small file in /usr/doc/<pkg>, and no commands from
APH> maintainer scripts (not sure if this is possible)? Probably not.
This script is necessary. But this is not a problem. The maintainers calls
dh_dhelp in debian/rules. That#s it.
---------
Let us start with the <directory> structure. Could you please post the
structure of menu?
cu, Marco
--
Uni: Budde@tu-harburg.de Fido: 2:240/5202.15
Mailbox: mbudde@hqsys.antar.com http://www.tu-harburg.de/~semb2204/
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: