Re: Debian Documentation Hierarchy
[Catching up here, back at home again for me.]
Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de> writes:
> On Sun, Apr 19, 1998 at 11:55:41PM +0200, Christian Schwarz wrote:
> > With that, I'm thinking of the following: Wouldn'd it be good to
> > suggest that our online menu systems don't create a new menu page for
> > each section of level 3 or below? For example, the entries in
> > instadm/hardware/hd could probably all be listed on a single page.
>
> YES! I'm glad that you have the same idea as I had. I didn't mention
> it, however, because it is part of implementation (front end), and
> I'm not sure about the relationship of doc-base and dww and dhelp
> yet (I'm a bit confused ;)
Well, let me elucidate my understanding of what doc-base will be for
Debian 2.1. It's pretty close to what it does now.
Primary function:
* handle registration of debian documents, enforce debian
documentation policy where reasonable and necessary
* this consistent system-wide registry will enable both display and
conversion system, although doc-base will be indepentant of these
functions.
Goals:
* modularity of design; no hardcoded knowledge of various
documentation display systems (info, dwww, dhelp)
* ease of use by debian package developers (i.e., in maintainer scripts)
* utmost rebustness in the face of package remove, purging,
reinstallation, multiply shared /usr or /usr/doc dirs, etc.
* minimize system impact for end-user (i.e., installation speed)
As you can see, I'm hoping to remove any knowledge of dhelp/dwww from
doc-base proper, and have document registry occur through doc-base,
which fires a series of hooks for the various installed documentation
systems. As an example, I'm considering '/usr/lib/doc-base/methods/',
which would contain files for the various systems, perhaps one file
describing what events to hook into (package installation), and anther
file or files (scripts) defining the actions to take (i.e., run
'update-menus' or what have you).
This type of arrangement would decouple doc-base from the dww/dhelp,
i.e., if dhelp_parse syntax changed right now, I'd have to re-release
doc-base to accomodate that, which is sub-optimal.
As you all know, my first priority now is setting the file format
standards to Marcus and I can have the beginnings of our Slink Debian
Documentation Policy.
> However, we certainly should make the relationship closer. I already
> added some recommendations for the front-end, and I'll add this
> point. It is not so easy, though, because the status may change, and
> at some point it would be wiser to create a new page or the other
> way round. Could we have a flag for this, that I can toggle? For
> example, sections marked with this flag would not have any
> subsections, but indentations (for example). I'll add such a flag
> where appropriate until we have another solution.
I suggest we eliminate this sort of feature creep until we get at
least a working prototype system so we can take a look.
> > - You don't say anything about how different languages of the documents
> > are managed. I think this should be explained somewhere, for
> > completeness.
>
> The issue is not resolved yet. In the front-end, I prefer the flags
> (when in graphic mode) or locales ("DE", "EN") when in text mode,
> presented after the document name.
>
> -------------------------
> The GIMP (en, de, it)
> An ultimative experience for every graphic designer.
> -------------------------
>
> In the document hierarchie, I don't know. Please tell me what is the
> current status of the discussion?
I currently believe that document language is an attribute of a
particular flavor of a document, and as such it should be handled as
such in the docid registration file. Display issues, again, are my
least concern right now; I want to *enable* radically effective
display systems, without actually telling them how they should go
about it.
> This is the reason why I want total control over sections. I think
> letting document registrations create sections will lead to
> sloppyness and inconsistency in the long run. If no section is
> appropriate, it should be created with the structure of the whole
> DDH in mind, which would be my task. It would also allow to move or
> duplicate some related documents.
While I definately sympathize with your concern here, I feel that the
best solution would be to *codify* sectional units, while still
allowing the creation of subdirs within sectional units. To my mind,
the issue of whether it may make sense to place a bunch of
app-specific documents in a subdir is an issue which is akin to what
we do in /etc, and should be placed under the control of the package
maintainer.
> > I'd suggest that you set up a web page where maintainers can look up
> > the current (authoritative) version of the DDH. From time to time, you
> > could tell the doc-base maintainer (via mail or by a bug report) to
> > update the package (but this doesn't have to be done too often I
> > think). Do you think this would be a working solution?
>
> Yes! I hope Adam does agree, too. And I hope he will not get annoyed
> when I mess things up ;) No, serious: I expect a very stable DDH
> ready for 2.1.
I'm not worried. Here is how I suggest we proceed with respect to the
emerging debian documentation policy and doc-base. I already manage
my sources with CVS locally; this should be moved to a cvs repository
under my administrative control at cvs.debian.org. Then I'll give you
(Marcus) or any other desirous and competent policy makers access to
the repository, and at my discretion I'll build a deb out of these.
I.e., I could act as a release manager.
Marcus, this is the std way we do collaborative packages (i.e., dpkg,
deity). Do you know CVS? Does this sound good?
Actually, I wouldn't mind having an "understudy release manager"
uncase something goes dreadfully wrong and I'm not available. I think
a central repository would be good. Of course I would retain ultimate
responsibility for the quality of the release.
> I make the following suggestion: I'll try a "dry run", will write
> descriptions and definition for the sections, and I'll write document
> registrations for as much documentation as I can find in Debian.
>
> Then, probably at the end of March, when Debian 2.0 is finally released,
> I'll make DDH fully official and authoritative for all developers, and
> have a bunch of document registrations *ready* for a lot of packages
> (well, probably without "Abstract:" and the like), that I can send to
> the maintainers of the packages. This will also lead to fast
> implementation in Debian 2.1!
Wow, it's a lot of work. I don't quite agree with this flow; I think
once we have a solid heirarchy and documentation registration format
(docreg as Marco calls it I guess), we should float is by a broader
community -- first debian-policy, then maybe debian-devel. Once we
get signoff there we also need to determine some other issues, i.e.,
if a system which provides documentation complying with the guideline,
is it ok to submit a bug? If so, at this point, you could file your
"pre-rolled" docreg files for various packages as bugs (with patch
included) against the packages themselves.
> I think its highly time to read the Doc Base Manual for me ;)
Definately. I'm going to split out the actually documentation for
install-docs off the manual and actually there will be two separate
standalone documents, one for details on how to use 'install-docs',
and one on the actual debian documetation policy, with probably
SUBDOCs for the various subsections (i.e., DDH, registration file
format, etc).
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: