[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: CVS location for dselect documentation for beginners

Josip Rodin <joy@gkvk.hr> writes:

> > > > If in the DDP CVS area, should it be packaged as well?  I think it will
> > > > need to be...
> > > 
> > > It can be packaged from there too, I don't see how that would necessarily
> > > impede the packaging process.
> > 
> > No, it's just more work to be done is all....
> Is it packaged anywhere now?

Yes, install-doc.

> (install-doc perhaps? Last I checked, install-doc was entirely broken. :)

Broken how?  I don't see any serious bugs on that pkg.  Doesn't seem
broken to me.

> > > The FAQ needs a similar set of information so we could even keep this in the
> > > parent directory of the manuals tree and share it.
> > 
> > That is going to get a bit tricky if you are providing these as source
> > packages.
> I figured we can easily hack it with a bit of symlink creation in the
> makefiles.

Pardon if I say "ew".

> > What I would suggest doing as an alternative is to create a
> > 'common-deb-data' CVS module, and via the CVS modules functionality,
> > including this module with the various CVS modules that use it, e.g.,
> > the FAQ etc.  This would effectively do:
> > 
> >   CVS checked out appearance  Repository location
> >   --------------------------  ---------------------------------
> >   faq/                     -> ddp/manuals.sgml/faq
> >   faq/common-deb-data/     -> ddp/manuals.sgml/common-deb-data
> > 
> >   install/                 -> ddp/manuals.sgml/install
> >   install/common-deb-data/ -> ddp/manuals.sgml/common-deb-data
> Interesting. I didn't know one could do that.

Yes, let me know if you want help setting this stuff up, if you wanna
go this way.  It is a *little* wierd to have the same source in
multiple different source pkgs, but it's all shared in cvs so... and
much less gross than trying to work with symlinks between source pkgs
-- not even sure that latter approach could ever work very verbosely,
esp. if we're building source pkgs using cvs-buildpackage.

> > In fact, there are even deeper issues.  Are we happy with the way
> > we're using SGML conditional inclusion for porter stuff?  Aren't we
> > rather annoyed with the difficulty in validating that and the
> > complexity it presents to authors?  Should we move to another means of
> > marking up arch-specific sections?  If we were using DocBook, we could
> > use (pretty naturally) the 'arch' attribute on <para>, <phrase>, and
> > <section>, and then handle the presentation issues (should we have one
> > manual with arch-specific stuff simply styled/presented in a certain
> > way?  or one manual per arch as we have now?) in stylesheets.
> Yeah, I never did fancy the raw and inflexible nature of the conditionals in
> ddoc-sgml, it's just dumb at times.

I think we all agree with this.  However, I don't wanna couple these
two issues: making install-doc, release-notes, etc independant, and
simplifying our approach to multi-arch.  These are two completely
separate issues.

I honestly think that later on the install manual should be converted
to docbook and we work out XSL or DSSSL styling solution using the
DocBook arch attribute.  Mechanical translation from debiandoc to
docbook is pretty easy.  I think we *should* stay with single source,
multiple builds (one for each arch), using style parameters to control
that.  For styling, we should probably use XSL since DSSSL is starting
to fall behind and isn't maintained at the same level anymore.

> Then again, it's not going to be a major issue for sarge as we'll likely
> need less of that stuff because less architectures will be newly released
> with it. woody was pretty special in this regard. Yay for woody! :) I don't
> say that often enough...

Um, well, whether an arch is new or not isn't that much of a factor in
how much arch-dependant stuff is there.  The main factor is really how
much the software is able to mask the differents of the arch.  Some
things are just inherently arch-specific and always must be documented
arch-by-arch, especially things like boot loaders (I don't even see
any grub ports to non-i386 at all, although I would think it would be
technically possible0.

I think it would be a serious mistake to think we can eliminate the
arch-specific portions of the install manual.

...Adam Di Carlo..<adam@onshore-devel.com>...<URL:http://www.onshored.com/>

Reply to: