Re: Notes for DDP writers
On Mon, Feb 15, 1999 at 05:45:56PM -0500, Adam Di Carlo wrote:
> 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.
That is how generally Makefiles operate, isn't it? Like, `make CFLAGS=-O12`
and all the lower level makefiles will do the same.
> >> 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
Yes, I know how the web pages look, I just thought multiple directories
would be better. I thought about it, and realised you'd have to make
more and more symlinks to cope with the situation. So, yes, it is better
for all languages to be in one directory.
> > 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.
No, it is not a problem. It is nothing :'< I didn't even knew that there
are :(
> 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.
Agreed.
> 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.
>
> 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.
Great, this gets easier and easier with every line of text.
> I agree with JT that we should only put *officially* released info
> under www.debian.org/doc/
How would you define officially? Just the documents that were released
with hamm (at the moment, soon that'll be slink), and these versions?
If so, that removes any need to use DDP's current resources. JT just
needs to unpack the appropriate .debs in right places and that is it.
Presuming, that we have .debs for the official documents, do we?
Then I propose that $(www.debian.org)/doc/maint-guide gets removed from
that location, since it wouldn't belong there.
> > 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....
Explain this - what maintaining, work for webmasters or for authors of
the documents?
> >> 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.
Sorry, that was my error - I meant to say generate HTML from SGML on the
fly, because you can't view SGML in web browsers. Anyhow, it won't be
needed after you mentioned these other things.
> > 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.
[big snip]
> 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.)
All of it would work instantly? Then why didn't anyone come to this
before?
> Leave cvs:ddp/webpages as is and do *not* try to shim them into the
> website.
Most of its contents will be incorporated in /doc/index.wml, anyhow, or
do we wish just to do this, and not point anyone to the new locations? :)
--
enJoy -*/\*- http://jagor.srce.hr/~jrodin/
Reply to: