Re: Navigation, was Re: Idea : common dir and tree

["Greg Ferguson" <gferg@hoop.timonium.sgi.com>]

On Jul 27, 12:22pm, Stein Gjoen wrote:
> Subject: Re: Navigation, was Re: Idea : common dir and tree
>
> Greg Ferguson wrote:
> > On Jul 26,  2:49pm, Stein Gjoen wrote:
> > > Subject: Re: Navigation, was Re: Idea : common dir and tree
> > > Guylhem Aznar wrote:
> > > ...
> > > > Would you have time to sum up the current agreed propositions,
> > > > including dir. tree?
> > >
> > > I'll try:
> > >
> > >             Proposal v1.0
> [snip]
>
> > Some questions/comments:
> >
> > - With many potential files/HOWTOs, these additional sub-directories
> >   (PDF, text, etc) will be virtually unnoticed. We need to provide
> >   pointers to the sub-directories within the index.html files.
>
> Agreed. We might do it
>  - logically by listing each format for each HOWTO, with links that
>   point to the relevant sub directory
>  - structurally by having pointers straight to each sub directory for
>   those of us who like to browse more manually.
> I'd like to see both but this is in the end a web design issue
> rather than a file system layout issue.
>
> > - Will we utilize the single-page HOWTOs or the multi-page HOWTOs?
>
> Personally I don't like to page down huge numbers of short pages.
> How about making small HOWTOs (less then say 10 pages) into single
> files using --split=0 while the bigger HOWTOs remain splitted?

I think it might be better to keep it consistent, but I
suppose a determination based on *file size* could be done.


> > - What about HOWTOs that currently are contained in their own
> >   sub-directory? We need to consider that (all DocBook-authored
> >   HOWTOs are like that).
>
> I don't know how these work. Do they have to be in sub directories?
> If so that would have to be sub directories below HTML/ but it
> does make it harder to maintain the index.html files.

It's due to the naming convention used when processing the DocBook SGML.
We do not have names like Foobar-HOWTO.html,  Foobar-HOWTO-1.html,
etc. Instead, the names are generated off the id attribute of
the chapters/sections, and the top-level file is index.html. This
is nice when the document is self-contained in it's own directory.
Otherwise, we would need to do more work to fix this...files would
get clobbered (same name) if not stored in their own sub-dirs.

If we use the single-file HTML HOWTOs, we don't run into this
problem...it becomes a non-issue; *unless* a HOWTO contains
graphics. Once again, there could be a chance that the filenames
used for graphics will not be unique amongst/across HOWTOs, and
things could get clobbered.


> > - Need to provide a commonly-shared image directory, such as what
> >   we have now on www.linuxdoc.org (for call-outs, etc). Should be
> >   at the same level as the other sub-dirs (unless we munge the
> >   HTML to convert links/references).
>
> Sorry, I don't quite understand this.

Some graphics/admonitions are shared, such as footnote
markers, warning/caution symbols, etc. Those files are kept in
a shared directory - 'images' in the HOWTO area.


> > >          text/       - same HOWTOS but as plain text
> > > ...
> > >          PDF/        - same HOWTOS but as PDF
> > > ...
> > >          PostScript/
> > > ...
> > >          SGML/
> >
> > - Contains gzipped tar files or exploded (SGML) text + graphics files
> >   for each HOWTO? Again, possibly in their own sub-dirs.
>
> If people install these files on their hard disk it is probably
> because they have the capacity and the need in which case I feel
> we can leave the files untarred and uncompressed.
>
> If we are to make an LDP CD-ROM I feel we should have the files
> uncompressed there since we then have all the space we need.
>
> > - Do we need a split for linuxdoc v. docbook (?):
> >
> >            SGML/
> >                 docbook/
> >                 linuxdoc/
>
> I had hoped we didn't need that. The first few lines of each file
> identifies the DTD anyway.

I suppose so.


> > > ...
> > >          HTML/
> > > ...
> >
> > - Is it just me, or is anyone else annoyed by upper/mixed-case? :-)
> >   I'd personally like to see lower-case used for all the sub-dir
names,
> >   but that's simply a personal preference.
>
> Normally I have mixed feelings about it but in this case I favour
> starting the main sub directories with a capital letter so they
> appear at the top of a directory listing. Perhaps text/ should
> then rather be Text/ to keep in the same style.

That won't ensure what you're trying to achieve (at least not with
a standard 'ls'), if all the HOWTOs are available at that level.
The first thing present will be the 3Dfx-HOWTO files, etc. You would
need to have something like 000_text, 000_html, 000_pdf...!


> The HOWTO/ directory will probably be full of HTML files so
> we should make the contents sub directories visible.

Right...so how is that best done? Again, I think putting the
HTML representations in the HTML sub-dir is the cleanest way
to achieve this goal. Plus, it's consistent with how the
other sub-dirs are used.


> > - What goes in the 'HTML' directory, given that all HTML HOWTOs will
> >   be in /usr/share/HOWTO ? Is it still necessary?
>
> I might have misunderstood but I got the impression the majority
> wanted HTML HOWTOs in HTML/ and I guess it can be an advantage to
> keep the root clean as it will hold a lot of navigational files.

Exactly. Agreed. I didn't think that was what was being proposed, at
least not from the intial document you sent(?).


> > >        GUIDES/       - the Guides in HTML format
> >
> > - Again, a decision on upper/lower/mixed case..perhaps:
> >   HOWTO, FAQ, guides, etc. Again, my personal preference.
> >
> > > Contents:
> > >
> > > [...]
> > >
> > > The index.html marked with (*) is based on the main page you see
> > > when you browse http://www.LinuxDoc.org/ with some minor exceptions:
> > >  - the links from that page point to files on disk using relative
> > > file:// URLs. Remember many do not have online access.
> >
> > All links on www.linuxdoc.org are currently relative (and work
> > in a local/non-web-server environment). We needed to have it this
> > way for our mirror sites.
>
> That probably makes things a bit easier. We will still need some
> kind of script to turn http:// into file:// and add the extra links.
> I any case I suspect we are going to need a fair bit of scripts
> to maintain and produce all this.
>
> [...]

r,



-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg@sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com  | 
Linux Doc Project - http://www.linuxdoc.org  |


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org