Re^4: document registration policy needing to be written
Am 13.04.98 schrieb apharris # burrito.onshore.com ...
Moin Adam!
APH> Well, I don't like the pseudo-SGML format. It should be real SGML, or
APH> not; I agree there.
Ok, then I would suggest a non-SGML format, because it#s difficult to
parse real SGML in C. Christian? Jim?
APH> That effort is called 'doc-base'. More below.
Well at the moment doc-base is only an other format :).
APH> * doc-base uses /usr/share/doc-base for package placement of
APH> registration files; dhelp uses /usr/doc/<package>. I'm not sure
APH> which technique is better nor why.
I think the second one (see other mail).
APH> * doc-base uses RFC-822 style field format; dhelp uses pseudo-SGML. I
APH> am sure that doc-base's format is superior.
I#m not, but if the other like the doc-base format, I don#t have a problem
to use it. Could you post a sample doc-base entry, please.
APH> * doc-base tries to be a generic document registration format; dhelp
APH> tries to just register and organize HTML files.
That#s right, we need a "Fileformat: " line. We should use something like
that:
Fileformat: SGML (sgml-tools)
Fileformat: SGML (docbook)
Fileformat: PS
I think, "Fileformat: HTML" should optional (not needed), because HTML
will be our standard format. All packages should ship HTML and SGML if
possible (and if possible in two packages). If there#s no SGML/TEXI file,
for example PS should be shiped.
APH> You seem to be contradicting yourself. Either one file format and
APH> registration system, or one for HTML and one for everything else. As
No that#s no necessary, see "Fileformat: ".
APH> you already know, I'm for one registration system, which allows other
APH> document *presentation* systems (i.e., dwww, dhelp, whatever else)
APH> hook into it.
I like this, too. But we have to talk about the way of connection.
APH> For instance, if I ship PS files, do I ship them A4? Letter? 4up?
That#s easy: English documents will be shiped in Letter and for example
German documents in A4. What#s 4up? "psnup -4"?
APH> No one PS file will really allow everyone to print the way they want
APH> to.
That#s right, but the advantage of different page formats will introduce
other disadvantages. As upstream maintainer of the German HOWTOs I can
tell you, that no converter will produce the best quality.
Take for example sgml-tools (and this is one of the better converters).
How will you manage the different char sets (7 Bit, Latin 1) and for
example special TEX styles (you need for example german.sty). And for
example the linuxdoc.sty has got some problems with the german.sty. And
the official version of the German HOWTOs in PS use the times.sty for
betty quality.
Another converter would be latex2html. Have you worked with this program?
The quality isn#t good (for example some tables are converted to gif and a
lot of gifs are on a wrong page).
That#re the reasons why I#m not a big friend of such a conversion. But I
don#t know a good solution for this problem at the moment.
APH> I would actually prefer to back-burner the conversion questions until
APH> (a) I've read the 1997 discussions on conversion, and (b) we have a
APH> strong, solid consensus on document registration.
Ok, but we can add an tag for this conversion in "our" file.
APH> Why not?
Because at the moment (0.3.6) .dhelp files have to be in /usr/doc.
APH> What is the benefit of your system of putting .dhelp files
APH> under /usr/doc/<pkg>? One of the requirements of dhelp_parse is that
(see other mail)
APH> the file should not be modified while it is in the database, or else
APH> it cannot ever be unregistered. Putting the file out of harms way (in
APH> /usr/share/doc-base, e.g.) is much less likely to be mucked with by a
APH> curious user.
Most users will never recognize the file, because it#s hidden :).
APH> Why bad? Please give reasons why you think it's bad, Marco.
I#ve got problems for example with the blank at the beginning, with the
point for a new line (why is that necessary?) and the parser of control
seems to have problems with line breaks at the end of the file (or missing
breaks, I#m not 100% sure).
APH> * already understood by our target users, i.e., pkg maintainers;
APH> it's identical to the dpkg control file format
I agree 100%.
APH> * Internet standard (RFC 822). Any format which is not based on an
APH> open standard is utterly unacceptable, IMO.
Is that the standard for emails?
APH> * easily legible and parsable
The second one is true, but not the first one. I think that for example
SGML is better legible. But if you and the others like the control format,
we could use it. No problem.
APH> Marco, you sound like a skipping record. ;)
Ok, sorry :).
APH> > CS> .
APH> > This should be <p>.
APH> Hmm. This is one area where we diverge from RFC822. '<p>' is an
If haven#t read it yet, but I don#t think so.
APH> interesting suggestion; however my problem is that since HTML 3.2, <p>
APH> is a container, not just a separator, so it's rather bad usage.
That#s right. I think that there shouldn#t any character for a new line in
"our" format. You (or Christian?) suggested that the description can
include HTML tags (as already used by dhelp). So there#s no need for
something like "."
APH> You should. dhelp only consults it's registration file for the
APH> purposes of adding it to it's proprietary (and fast) indexing scheme,
APH> in /var/lib/dhelp/dbase. If we could modify dhelp to read
APH> /usr/shared/doc-base/<file> directly, that would be *far* better.
Yes, I#ll support "our" format and I#ll drop support for ".dhelp" (maybe
in Debian 2.2).
APH> What does a format have to do with a particular parser's
APH> implementation? I don't understand why any "format" would require
APH> Perl??
Because some formats like SGML are difficult to parse with a C program.
APH> * Debian should have a single document registration system which is
APH> equipped to be used for system-wide document registration to enable
APH> display systems to give structured display and searching for these
APH> files.
Ok.
APH> * It would be *extremely nice* if dhelp could support doc-base files
APH> directly rather than having us create a separate file (with no
APH> additional information) for dhelp.
No problem, if we#ve discussed and voted for one format.
APH> * Document registration files should not be placed under areas of
APH> package control, i.e., /usr/doc/<pkg>, but rather in a shared
APH> directory especially for this purpose.
I disagree.
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: