Re: Debian Documentation Hierarchy
On Mon, Apr 27, 1998 at 03:44:33AM -0400, Adam P. Harris wrote:
>
> [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)
Okay, thank you for the summary. It is close to what picture I had in my
mind.
> 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.
Sounds good.
> 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.
Okay, thank you!
> > 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.
Well, it was only an *idea* to make people happy who disagreed with the fine
graduation of sections in the ddh. What CS and me are pointing out here is,
that another level in the ddh doesn't need to mean another level to click on
the screen. This relativates the depth of the structure.
> > > - 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.
Yes.
> > 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'm not sure if I agree or not. However, this is what Marco and me worked
out (coming from totally? different positions):
A package may create subsections, but the subsection becomes a part of the
DDH when multiple packages (two or more) want to use the same (or a very
similar) subsection.
For the benefit of the user and for the functionality of the over-all design
of the DDH, it is essential that the documents are splitted among the DDH in
the defined way --- user manuals below user, development documents below
devel and so on. Just dropping all sort of documents in a single (created)
section is quite confusing, IMHO. Personally, I consider a wrong placed document
as a bug.
This is a bit different from /etc, because the user wants to find the
documentation in the appropriate section. The situation is more akin to
/usr/share, /usr/ and /, opposite to using just a /opt directory.
Most likely this is not at all what you meant, but I thought I would spell
it out, to make my intentions clear.
As long as the purpose of DDH defined sections is clear, and only a single
package uses one or more subsections in the appropriate locations, all is
fine.
> > > 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?
This sounds very good. I know what CVS is, but I need to learn the technical
details (I didn't have write access to one before). However, this should be
no problem. I have no problems with you acting as a release manager.
> 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.
We already have the non-maintainer-release procedure for crisis, let's not
make things more complicated than they are.
> > 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.
Well, I meant that I would write them for my own use, for testing and moving
them around until they fit in nicely. However, for the documents I wrote
such entries, it would be a doubled effort if I wouldn't provide them.
At the moment, I have to admit that things didn't work out as intended. I
was very busy at the weekend, and will be so for two further days. However,
I may be busy but I'm not away. It just means that I won't have the second
draft ready before Thursday.
> > 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).
Well, I read it in the meanwhile. I think, splitting it is a good idea in
general.
Thank you for your comments,
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: