Re: HOWTO filenames

[Stein Gjoen <sgjoen@mail.nyx.net>]

Some snipping ahead...

Bill Staehle wrote:
> Jorge Godoy <godoy@conectiva.com> wrote:

> >I suggest removing the words "HOWTO" and "mini-HOWTO" from
> >filenames. They are already present at the directory / place they are
> >stored at LDP.
> 
> That gets confusing _after_ I download them. Were they a HOWTO, or a mini?
> 
> (Yes, I try to download them to separate directories in ./new-HOWTO and
> ./new-mini until I read them, but does everyone do this?)

The distinction between HOWTOs and mini-HOWTOs is going away and has
already so to some extent as all mini-HOWTOs now are supposed to be
written and maintained in SGML.

An LDP file hierarchy is in early design phases that will finalise
the transition. It seems that job has more or less landed with me
but due to large workload at my day job I have had to put this on
the back burner.

> >I would suggest extending this rule to document titles, but in a
> >reverse manner: add the word "HOWTO" (no minis) to document titles. It
> >will help people who downloads them to know to what LDP category these
> >documents belong to.
> 
> I'm not sure what this means. Is this the title within the document, as
> opposed to the filename?

I suggest keeping names short and to the point. In the upcoming
hierarchy the location tells you what it is, format and language.
Therefore I believe we can shave "mini" and "HOWTO" off the file names.

> Certainly when I download documents (other than HOWTOs and minis which end
> up in specific directories on my system), I always check to see that a
> definitive name (usually a URL) is at the top or bottom of the document, so
> when later referenced, I know where to check to see if the document is the
> latest/greatest, and where to send others to find it.

If you download HTML files the text between the <title></title>
tags should tell you quickly what the file is about. For plain text
files you could use 'head' to get teh first few lines of the file.

> David Lawyer <dave@lafn.org>   then replied:
> 
> >For the directories that contain them on PCs, shortening the names might
> >permit more to display on the screen.  On my PC they all end with
> >-HOWTO.txt.gz.  The gz is important to make it easy for the viewer (pager,
> >editor, etc.) to know it needs decompression.
> 
> .gz, .Z, .zip, what ever - yes, but that is how the file is stored on the
> system in question. I happen to gzip the HOWTOs, but not minis. This was how
> they were delivered on the first distribution I used and I've just continued
> that. But that is a personal option.
> 
> >txt is helpful too.
> 
> If that makes the viewer know how to decipher the file format? I dunno, I'm
> not using DOS/Windows any more. But is the SGML format otherwise somehow
> confusing to viewing tools? I'm dumb, and use 'less' to read most documents
> in an XTerm.

The utility 'file' will on Linux (and most Unix variants) tell you
what type of file you have, without filling your screen with garbled
text from a binary.

I too use 'less' to view text files, you could also try the
X11 cousin 'xless'. Can anyone recommend a good plain text viewer?

> >HOWTO is less important.  But some entries are long like:
> >Unix-and-Internet-Fundamentals-HOWTO.txt.gz and not much would be
> >saved by removing the HOWTO.
> 
> That's pushing it, but 'Unix-and-Internet-Fundamentals-HOWTO' is 37
> characters, and allows /bin/ls to list it in two columns on an 80 character
> wide display, while adding the .txt OR .gz extensions runs it over 39,
> meaning /bin/ls gives me one file name per line. Of course, I _do_ get that
> anyway if I pipe ls to more or less.
> 
> On the other hand, Midnight Commander (which I rarely use) defaults to
> displaying one column listings on this box, with the file name shortened if
> the display is not wide enough. Thus, I find 'Unix-and-~OWTO.gz'

I would recommend file names that are readable even in 8+3 format.
This should probably go into the LAG but it is also something
reviewers might keep an eye out for.

Regards,
   Stein Gjoen


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