[blfs-dev] Rules of the BLFS book about short descriptions....

Ken Moffat zarniwhoop at ntlworld.com
Mon Aug 17 11:07:14 PDT 2015


On Mon, Aug 17, 2015 at 07:08:05PM +0200, Denis Mugnier wrote:
> Hi,
> 
> As you can see, I add some short descriptions where I can find a
> description. I think that it is useful. And if a short description for a
> binary is written, you can find the binary on the index page (see
> http://www.linuxfromscratch.org/blfs/view/svn/longindex.html).
> 
> About short descriptions, the mariadb page says :
> 
> "Descriptions of all the programs and libraries would be several pages long.
> Instead, consult the man pages or the online documentation at ..."
> 
> The rule of the BLFS book is to not list short descriptions when a package
> provide many programs ?
> 

I think it has always been a question of how practical it is to list
them.  And for descriptions there is then the question whether anybody
has worked out what a program (or library) does.

> For example, the sg3_utils page
> (http://www.linuxfromscratch.org/blfs/view/svn/general/sg3_utils.html)
> describe 70 binaries ("only" 49 for the mariadb package).
> 
> I think that the BLFS book is a reference book. The reader can find
> information about many packages. And for me, short descriptions are a part
> of this information.
> 
> Agree or not to add all short descriptions for all packages ?
> 

I very much enjoy being able to look in the longindex, both to see
which package provides a program I have seen referenced elsewhere,
and to see what it does.  So, I like the idea.  But see below...

> ok, I know that it is a long job, and your time is not elastic ;o)... but if
> I add all theses short descriptions ?
> 
> Now, it is my way of contributing.
> 

Please consider what you will do when you get to a *big* package ;-)

I had thought about adding details for the texlive programs.
Possibly a few are so obscure that they will not produce any
meaningful description.  But there are many other programs with some
documentation.  If I was doing this, I would NOT think that merely
saying 'foo (symlink to bar)' was useful in texlive - many of the
executables do quite different things when called by different
names.  So, allowing for blank lines between the descriptions, there
would be (at a guess) more than 500 lines of description in texlive.

If somebody was doing that (perhaps as an appendix ?), I would
suggest that for the tl binary the correct approach would be to say
"see descriptions in texlive (with link) (or new appendix), asymptote
(link), biber (link), xindy (link).

ĸen
-- 
This one goes up to eleven: but only on a clear day, with the wind in
the right direction.


More information about the blfs-dev mailing list