Re: RFC: Changing of /doc/manuals/ implementation
Rob Bradford wrote:
> On Mon, 2002-09-09 at 16:26, Martin Schulze wrote:
> > Rob Bradford wrote:
> > > I'm proposing a new hierarchy for the /doc/manuals/ tree.
> >
> > I'd like to object, if I may...
> >
> > > My suggestion for the hierarchy is as follows:
> > >
> > > /doc/manuals/<lang>/<manual-name>/<format>/
> >
> > Hmm, I just noticed something odd:
> >
> > HTML /doc/manuals/<manual-name>/
> > other /doc/manuals/<lang>/<manual-name>.<format>.<suffix>
> >
> > I wonder why this isn't implemented like:
> >
> > HTML /doc/manuals/<manual-name>/
> > other /doc/manuals/<manual-name>/<manual-name>.<lang><format>.<suffix>
>
> Is this a directory? If so use a / if not, how do you deal with the
> chapter seperation for html? :(
To make clear which is a directory and which is a file, I've added a
trailing slash for all directories. Hence, the line starting with
"other" refers to files instead of directories.
> So long as there is an index for the various formats languages as
> index.html within the directory. Someone pointed out to me that there
> was no way of knowing if a pdf/ps was available because index.html was
> the first page of the manual.
This could easily be done (needs to be implemented, though, but if
nobody steps forward, you could count on me implementing it).
Links to other formats are added from the main ddp index pages, not
from individual pages. This could be improved, I agree.
Let's take a look at an example, would the following match your
intention?
Manual be "reference"
HTML /doc/manuals/reference/reference.<lang>.html
/doc/manuals/reference/ch-preface.<lang>.html
...
PDF /doc/manuals/reference/reference.<lang>.pdf
PS /doc/manuals/reference/reference.<lang>.ps.gz
INDEX /doc/manuals/reference/index.<lang>.html
The INDEX files need to be created by a script during the build of the
DDP. This will require some tweaking and modifying the HTML output
with something like s/index.<lang>.html/<man>.<lang>.html/g, but it's
doable.
> I'm just interested in tidying this up as i had to ssh into gluck to
> identify if a pdf of a manual was available for a friend.
Ouch! I thought they were referenced from the ddp index pages, so
didn't pay attention to it. As a sidenote, I seem to recall that
there are tons of PDF errors during building of the release notes. I
guess this requires some investigation as well.
Personally, I would like to keep the current structure where possible
since it provides easy to recall and short links -- if they fit into
the structure, which doesn't seem to be the case for all manuals.
I'd also like to not add too many directory levels that need to be
supported with special index files. This could make it more difficult
for people to reach the file and will require the creation of more and
more multilingual index files outside of wml.
I'd be willing to help with tidying up.
Regards,
Joey
--
It's practically impossible to look at a penguin and feel angry.
Reply to: