Re: Documenation Update and Query
OK, as you requested I have committed my current ch 5 to cvs.
Before I did so, I tagged documentation/en with rb00 to make it easier
to back out.
Yes, the restructuring is a bigger job than it seemed--particularly
when looking just at one architecture's docs! It was the downloadable
file section I had started when I needed some sleep.
If by high level hacking you mean basic moving the sections around, I
have not finished with that--this is literally a snapshot of where I
am now.
My thought is to organize the files by installation stages, so that
the subsections (<sect1>) would be
documentation
boot files (root/rescue)
utilities
drivers
base
beyond
This is partly to make it easy for people to see what they need if
they switch from diskettes to anything else.
I remain skeptical that this section needs to provide links to each
individual file. First, it does make it more likely the documentation
will be out of sync with the files. Second, do we really think anyone
is going to download 14 bootfloppies by selectively clicking on html
links, when they can go to the right direct and just pull off the
files they need? Third, there is the unresolved formatting problem.
In the interests of not rocking the boat I was planning to leave all
the links in (despite what I just said). In the interest of
formatting, I was going to use generic headings, and put the files in
the item text. Apparently the formatting problem (the failure to
wrap) is only a problem for titles/headings.
Aside from the editorial question of what to do, actually doing it
will require a lot of cut and pasting.
The other high level issue the rewrite raises is incorporating
material on the different flavors and subarch's into the main doc. I
basically copied the writeup of the different i386 flavors into the
install manual, but that is not a desirable long term strategy.
On Mon, May 01, 2000 at 09:52:46PM -0400, Adam Di Carlo wrote:
> Ross Boylan <RossBoylan@stanfordalumni.org> writes:
>
> > I am in the middle of a complete overhaul of ch 5, Installation
> > Methods. It is not in a committable state, so this is just a heads
> > up.
>
> You better watch out because I've been hacking on that in CVS also.
> I assume what you mean is the organizational update, right?
>
> After going thru a little bit and updating the system (so that the
> links work right for LINGUA != C, for www.debian.org distribution,
> with Bruce Sass correcting the file names), I more than ever believe
> that the "downloadable files" section really does need to be
> re-organized and restructured.
>
> However, we need to synchronize a little better, or we're going to get
> into nasty conflict situations in en/inst-methods.sgml and
> defaults.ent.
>
> I would ask you to do any of the high-level hacking and commit that
> even if things aren't complete, if possible.
Reply to: