Re: some suggestions for docreg
On Wed, Apr 29, 1998 at 07:47:00PM +0100, Marco Budde wrote:
> Hi!
>
> Here#re some suggestions for our docreg file format:
>
> * If we use the doc-base format as basis, we should rename "Document: " to
> something like "DocID: ".
>
> * It should be possibly to register several documents in one file.
> "DocID: " should start a new document in the file.
Yes.
> * We should rename "Files: " to "File: ", because it#s only one file.
Makes sense to me.
> * Only one "Format: " entry/document should be allowed; the newline
> between Section and Format should be removed, because the newline
> is a sign for a the next document.
The latter doesn't matter, as "DocID" marks the beginning of the next
document. Newlines should be ignored.
> * "Language: "
Yes, a difficult matter. Do we need a different DocID for every translation,
or do we use the same DocID and distinguish via Language: entry?
Translations should be recognized as such, so the DocID should be the same?
> * "Title_eng: " (maybe we can find a better name). This tag is necessary
> for international documents, because the filename and the title is not
> enough to find the translation of for example the "Printing HOWTO". This
> document is called "Drucker HOWTO" in German and has got another file
> name.
I don't understand this. The unique mark is the DocID, maybe this should be
used? Maybe I'm missing your point here...
> * "File: http://"; is the sign for an URL.
Do we allow external links? The front-end should mark them as such.
PROPOSAL: I add a link to the Debian Home Page in the Debian Directory. This
one link should be there as soon as doc-base is installed, I think. Do you
agree that this makes sense? Doing this would mean to extend the purpose of
DDH from a simple (who said that ;) directory structure to a default
framework of sections and (one?, two??) default entries, like the following:
DocID: ddh-en-debian.home
Format: html
Language: en
Section: debian
Title: Debian Home Page
Abstract: The main site of Debian in the World Wide Web. Browse the list of
available packages, get information about security issues and the open bug
reports. Read news about the current development of Debian.
Note: I'm not speaking about 50 default doc entries, not even about 5. I just got
the idea for this single entry. I can hardly think of any more that make
sense in the ddh (I can think of some links for packages, but this is
unrelated ;).
> * "Format: dir" is the sign for a directory description. The following
> tags are allowed:
>
> DocID:
> Format: dir
> Language: de, es, ...
> Section: HOWTO/mini (only one entry is allowed!)
> Abstract:
You obviously forgot "Title:". I'm not sure how the "Language:" Tag should
be handled in conjunction with "DocID", see above. The rest seems okay.
> * "Format: link" is the sign for a link to a directory:
>
> DocID:
> Format: link
> File: @../HOWTO
> Section: devel/foo
Again, "Title:" is missing. I don't like the "File:" format for links.
Links should be absolute to the root directory, this is more safe, makes it
more easy to maintain and is independent from the representation in the
file system. It requires only a slightly amount more parsing by the scripts,
if at all (you can just pre-pend the right number of "../" pieces):
Format: link
File: debian/devel/foobar
Doc Base should refuse to register a document that is not in a valid section
(no link name allowed).
Marcus
--
"Rhubarb is no Egyptian god." Debian GNU/Linux finger brinkmd@
Marcus Brinkmann http://www.debian.org master.debian.org
Marcus.Brinkmann@ruhr-uni-bochum.de for public PGP Key
http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/ PGP Key ID 36E7CD09
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: