[blfs-dev] Rules of the BLFS book about short descriptions....
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:
> 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
> 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
> 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).
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