Re: unionfs Documentation

[Thomas Schwinge]

Hello!

On Sun, Aug 16, 2009 at 08:06:28PM +0200, olafBuddenhagen@gmx.net wrote:
> On Tue, Aug 04, 2009 at 01:00:10AM +0200, Thomas Schwinge wrote:
> > On Fri, Jul 17, 2009 at 05:08:28AM +0200, olafBuddenhagen@gmx.net wrote:
> > > On Sat, Jun 13, 2009 at 09:23:23AM +0300, Sergiu Ivanov wrote:
> > > > I'm sending in my attempt to compile a unionfs documentation. It
> > > > is formatted as a stand-alone Texinfo file for now, so that I am
> > > > able to build and view .info files from it.
> [...]
> > > put it in the normal Hurd manual, where the "shadowfs" placeholder
> > > used to be.
> > 
> > I disagree: let's please put it into the unionfs repository and render
> > into a separate info file.  Sergiu, then please remove the shadowfs
> > reference(s) from the GNU Hurd Reference Manual.  unionfs is not an
> > integral core part of the GNU Hurd kernel infrastructure, even is held
> > in a separate repository, and thus doesn't really belong into the
> > GHRM.
> 
> It certainly was *meant* to be, as evidenced both by the mention in the
> design document, and by the placeholder in the manual.

Which design document do you mean?

The placeholder in the manual was added in mid-1998 by Gordon Matzigkeit,
when he overhauled it in various parts.  I wouldn't interpret too much
into him having added a stub node.

> It was a mistake that unionfs was not added to the main repository in
> the first place. This should be fixed, rather than proliferated.

Strong words for a simple technical decision that I have done (that is,
not to keep every software package in one single Git repository).  All
this is only about physical structure, which by no means dictates how all
the packages are eventually to be used in the assembled GNU system.

> > (Of course I'm not saying that unionfs was an unimportant part for the
> > envisoned GNU system.)
> 
> The vision hasn't changed, to the best of my knowledge.

Sure, that's what I was saying.  And you are correct: this is absolutely
relevant for the GNU system.  But here we are talking about the
repositories that hold the sources of some Hurd components, and how to
structure these, and not about the GNU system, which is a distinct (and
different) project (and on hold at the moment, as far as I can tell).
The Hurd components are as service-provider for the GNU system, as they
are for Debian GNU/Hurd.  The GNU system depends on a highly-functional
unionfs, but the Hurd components themselves do not.


> > > > @node Basic Internals
> > > > @chapter Basic Internals
> > > > @cindex internals, node, light node, conflict
> > > > 
> > > > In this chapter a short description of how @command{unionfs} works
> > > > will be done. This description is intended for people who have at
> > > > least a vague idea about GNU/Hurd translator programming.
> > > > 
> > > > Note that what follows is an overview of the basic functionality.
> > > 
> > > I don't think the introduction paragraphs are necessary.
> > 
> > Without having at all looked at them so far, why remove them?
> 
> A meaningful title, like "implementation", is sufficient. You don't need
> two paragraphs to explain what this is. People reading the manual aren't
> morons. Bloating the text with useless fluff only makes it harder to
> read.

I now had a look at this chapter.  This ``useless fluff'' is a
description about how this unionfs implementation works internatlly.  I
still don't see why you wouldn't want to publish this information in the
manual?  Or are we somehow talking past each other?


Regards,
 Thomas

signature.asc
Description: Digital signature