Re: Notes for DDP writers
> On Mon, Feb 15, 1999 at 01:00:40PM -0500, James A. Treacy wrote:
> So, I can merge the DDP pages and doc/index.wml page, and send them to you?
I'd personally like to be a little more comfortable on the scheme you
are using.
>> > What we could now, is to create the preffered directory structure under
>> > /doc/, and making a small symlink farm ( :) ) in these directories that
>> > would point to the current locations of debian-doc documents.
>> > That would enable all the stuff you are saying, without actual moving
>> > of the HTML documents from their current locations (we'd do that later).
You should take a closer look at DDP's manuals.sgml Makefile system.
It was designed for people to be able to tweak a single variable,
which can be set on the command line, and install all the files into
subdirectories on any given prefix.
I don't understand why we even wanna bother with a 'symlink farm'; it
doesn't seem necessary at all. All the functionality is there.
>> > Lets say first:
>> >
>> > /doc/ -- the toplevel index files
>> > stable -- index files for 'stable' docs
>> > tutorial -- index.$LANG.html -> symlink to $LANG/index.html
>> > en -- \
>> > fr --- language specific versions of docs
>> > de -- /
>> > ...
>> What's the point? Why not simply put all the languages together?
> Some documents are divided in several files, so I thought it would
> be more convenient not having to change the names of them all, instead
> just put them in another dir. But it can be done in one directory.
See bug#33354. Content negotiation specifically requires we do *not*
use separate subdirs. Quoting from the bug report:
| -rw-rw-r-- 1 treacy Debian 4119 Feb 10 10:46 index.de.html
| -rw-rw-r-- 1 treacy Debian 3635 Feb 10 10:22 index.en.html
| -rw-rw-r-- 1 treacy Debian 3680 Feb 10 15:20 index.hr.html
| lrwxrwxrwx 1 treacy Debian 13 Feb 10 10:22 index.html -> index.en.html
| -rw-rw-r-- 1 treacy Debian 4365 Feb 10 10:52 index.ja.html
> BTW there are no translations to debian-doc documents yet, AFAIK,
> but we have to be prepared ;|
There certainly *are* translations of most of the documents in the DDP
area, at least, the mature documents. They are simply uncollected at
this point, which is a big problem.
Again, with the bug report, we can anticipate that debiandoc-sgml will
support content-negotiated file naming in the near future. I propose
we put translated SGML in the same DDP cvs areas as the manuals, and
extend our build system to loop through all available languages. This
is not something we have to implement now (without debiandoc-sgml
support, we can't get far anyhow), but we need to make sure we *plan*
for it.
>> > The documents in 'stable' directory would be picked either by the version
>> > in current stable release, or by stability of the doc. We could rename
>> > these to 'finished' and 'current' or something else.
>> >
>> > That way, when /devel/index.html would need to reference Debian Policy
>> > document, then you'd point it to http://www.debian.org/doc/stable/policy
>> > (or relative link), and not have to worry, since the debian-doc group
>> > would actually pick the doc to put on that location(s).
>> >
>> Why put the development version in the Debian web space? It then gets
>> unnecessarily mirrored all over which wastes bandwidth and disk space
>> (some of the mirrors don't have a lot of extra space).
> Some documents are much improved from the version that got released
> in last 'stable'. Then you have the Debian Policy that really should
> be the latest version. Besides those, there are some docs that haven't
> yet been released in a 'stable'.
I think this is already served by the DDP pages. All we have to do
for this is move the installation target for the nightly autobuild so
it's not under Oliver's user space web area. No need to invent this
all over again.
I agree with JT that we should only put *officially* released info
under www.debian.org/doc/
> Also, I doubt that all these docs take *that* much space, if you include
> just the HTML version.
> Anyhow, we can just have the latest versions on the web. I think most
> docs don't have any major showstoppers in their development versions.
The point is not to create more work. Think about the folks who have
to maintain this stuff for years....
>> Also, what is the purpose of all the symlinks? All this can be better handled
>> by CVS. Doing a 'cvs checkout /cvs/ddp/stable' (or something similar) could
>> grab the stable branch. If the files needed to be further processed, that
>> can be done on master.
> Yes, but that means that you must generate the SGML on the fly, since
> the debian-doc CVS tree contains only this format.
Not even close to true. The manuals.sgml area is pure SGML. I think
the only thing Debian webmasters care about is the manuals.sgml area.
> To the list readers: do you have any objections (hopefully better ideas)
> to the directories layout laid out in my previous message?
Yes, serious objections.
For simplicity, I propose:
www.debian.org/doc/
index.wml -- manually manipulated
manuals/ -- this subdir is under DDP cvs control
<manual-name>/ -- i.e., 'developers-reference'
Example tree:
www.debian.org/doc/manuals/project-history/
index.html
ch1.html
ch2.html
...
Once we have content negotiation:
www.debian.org/doc/manuals/project-history/
index.html -> index.en.html
index.en.html
index.de.html
ch1.html -> ch1.en.html
ch1.en.html
ch1.de.html
...
In short, all we have to do to support this is
'cd manuals.sgml ; make PUBLISHDIR=/org/www.debian.org/doc/manuals/'
Manually run this process when a new released version is
available. (Extra credit: determine an automated mechanism for this;
the only thing I can think of would require cvs branching which is too
much for most documenters to deal with, I'll warrent.)
Leave cvs:ddp/webpages as is and do *not* try to shim them into the
website.
Voila.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: