Catherine Gramze schreef op 29-12-2016 19:47:
On Thu, Dec 29, 2016 at 1:36 PM, Xen <l...@xenhideout.nl> wrote:
More importantly the man system or man format does not preclude such
documents being written as tutorials so basically it is being done
all around.
So your assertion here does not really have a basis in reality I
must say: the system does not preclude this from being done. People
can do it all they want, and they do it.
It is the people that insist on not doing it, that write poor man
pages.
I did not say the man page system precluded it, nor that no man
page was written in such a manner. I stated the original purpose and
design of the man page as a complete reference, and only a reference,
and the futility of wishing that all man pages would be re-written to
conform to your personal preferences. What you apparently consider
to be a "poorly written" man page I find to be highly accessible and
useful. Give me the command and the list of options, with a sentence
or so explaining the function of each option. Done. I can figure out
which options I need better than somebody not in my situation.
Examples muddy up the page and make it harder to scan the options for
what I need without adding any clarity to the function..
That's not what you said, dear sir. What you said was: "Trying to wish
the man pages into something they were never designed to be is likely to
be unsuccessful.".
Basically, you imply or directly state that their stated design goals
would interfere with becoming more introductory-text-oriented material
(more explanative, rather than just poorly descriptive). I think it is
clearly evident that the man page is clearly freeform as much as people
want it to be. So it is rather evident that the design goals do not
interfere with anything. Now again you state "the original purpose and
design of the man page" in conjunction with "the futility of thinking
(wishing) that all man pages would be re-written to conform to your
"personal preferences"" (my quote).
Any "original purpose and design" of the man page would only have any
bearing if through historical reasons the majority of man pages were
thus poorly constructed. I say that this is not even the case. Barring
that, those "original purposes and design goals" have no bearing
whatsoever on saying what can, and cannot be done. Moroever, this design
goal could very well change, or by evolution people could decide that
this design goal IS changing.
You go on by stating your personal preferences.
So I think we can conclude at least three things:
- you *are* implying that somehow the descriptive option-oriented format
is technically or at least principally (if, at the last instance,
historically) being favoured by some "design goals" that people once had
for the system. (That could also have been poor, as it is now).
- you are the one who is using personal preferences as a reason for
stuff to remain this way, not me. I am saying (and others are) that many
users, in fact, users or new users in general, cannot use the man system
to full extent because of these attitudes and opinions and styles of
writing these documents. So that is not personal preference at all but
rather the truth of how many experience this system.
I have said nothing about what I like or don't like. So you are the one
who is using what you like and don't like (or what works for you and
doesn't work for you) (I have not implicated my own person at all, thus
far) -- I have merely described how the system works and what
descriptive is and what task-oriented is.
So actually I think you are just projecting stuff onto me that really is
something you are doing, not me.
And
- NO where have I stated any "wish" for "all man pages" to be rewritten
according to those what you call "personal preferences" (actually they
are what would work for the majority of new users to any program) (and
what does work, and what many man page authors actually naturally and
intuitively do) -- but you call it futile. You misinterpret my intent
here little lady. I am not asking anyone to do any work.
I am simply saying there is no reason to keep man pages poor based on
some pre-existing notion of what they were initially intended to be.
Basically, you can judge formats on their own merit also considering, or
perhaps, predominantly also considering the position the man pages today
have in the system, in which the "alternatives" are unusable, so "that's
what /usr/share/doc is for" does not count. It doesn't work. No one goes
there.
It's too much trouble. The man system is automated and organized. The
/usr/share/doc system is manual labour. As far as I know at least?
I have certainly not ever seen any reference to this thing being
automated, other than the dysfunctional "info" system.
There are no other good reference materials other than the man system.
Certainly not for users wanting to have a quick hands on introduction or
guide into how to use the thing.
So saying "there are alternatives that do that thing" is just lies and
fallacy. It's not true. It doesn't work. That is wishful thinking
indeed.
It will never work the way it is, and it has never worked the way it is.
Only the man system works.
You must accept first that the man system is pretty much the only viable
"info" system we have in Linux in the console world.
And you will know that they are indeed used by all users as introductory
texts. Here is Grep:
"grep searches the named input FILEs (or standard input if no files are
named, or if a single hyphen-minus (-) is given as file name) for lines
containing a match to the given PATTERN. By default, grep prints the
matching lines."
Well, that is pretty introductory isn't it? It tells you exactly how to
use it. This is exactly what I mean, and exactly what is good writing.
What comes next is rather confusing, because it is so immaterial or
irrelevant as to the main program at that point:
"In addition, three variant programs egrep, fgrep and rgrep are
available. egrep is the same as grep -E. fgrep is the same as
grep -F. rgrep is the same as grep -r. Direct invocation as either
egrep or fgrep is deprecated, but is provided to allow historical
applications that rely on them to run unmodified."
Not something that makes all that much sense, especially given that no
one actually uses that (and it is deprecated, probably, because of it).
But still, that can be forgiven, the beginning is excellent.
The option descriptions are also just fine and the length of the
document is just about right, not too long, not too short.
No issue with this man page except for that paragraph.
Now aufs:
"Aufs is a stackable unification filesystem such as Unionfs, which uni‐
fies several directories and provides a merged single directory. In
the early days, aufs was entirely re-designed and re-implemented
Unionfs Version 1.x series. After many original ideas, approaches and
improvements, it becomes totally different from Unionfs while keeping
the basic features. See Unionfs Version 1.x series for the basic fea‐
tures. Recently, Unionfs Version 2.x series begin taking some of same
approaches to aufs's."
That's not a very concise intro. More historical than functional.
"At mount-time, the order of interpreting options is,
· simple flags, except xino/noxino and udba=notify
· branches
· xino/noxino
· udba=notify"
That's just incomprehensible. It doesn't start with the most common
options, when it should. That's no quick introductory text, that is a
complete manual written in a weird way. OpenSUSE does the same with some
of their man-pages, which are like books. (Try "man zipper"). There is
no point in starting out with ORDER of things if you haven't even
explained what those things ARE.
Then the syntax is just incomprehensible to begin with, and the
description of it also. That's just completely unusable until you see
some examples. So you skip down to the end of this very long page. And
then it is still hard to comprehend to see what it does and how it is
used, because the example aren't explained. So you go on the web and
find your answers instead. Dirt-poor man page. Much too long but that is
not the worst part. Poorly organized, doesn't explain that the system
functions around "branches" (directories) and that you can create mount
points based on 2 or more branches, but that you can also add and delete
those branches from a running system (running mount).
If it explained that _first_ then all of the other options would make
*more sense*.
So it's just poor writing from my perspective. Doesn't give examples
soon enough, and when it does give them they are too complicated. When
most users just want to do this:
mount -t aufs -o br:upper-dir=rw:lower-dir=ro none target-dir
Aufs has only two ordinary use cases:
- upper dir and lower dir
- both dirs are writeable and will see writes going to their respective
directories (on each "upper" directory)
If it would just explain those two use cases, people would get a clue.
Now they have to hunt the internet for that same information.
Because there is no lead-in explanatory text, users are now basically
forced to read the entirety of the man page before they start getting a
clue, or hunt around bits of information. So the speed of reading this
man page is now gone.
So miss Catherine you say you don't want examples and that you want a
man page to be a clean and concise list of options. The aufs man page is
clearly the opposite of that and it still fails to tutor people.
It lists all of the options, but it is a complex program and needs more
explanation. However it does this in reverse order, first starting with
something you cannot comprehend until you have read the remaining parts,
and all of the options are basically incomprehensible until you get the
full picture, which would not take more than 5 lines to address.
So precisely because it fails to answer a user's questions when they
arise, this is a poorly written man page.
For simple programs, like Grep, fine, that format is excellent. There is
no need to explain much and it is such a basic tool that the "quick and
easy list of options" format is enough.
But aufs or something like autofs needs much more explanation. And it
needs to do this in a "chronological" order starting with the stuff the
user first needs to understand, and then going on with the next.
If you display options for a program that hasn't been explained, it
doesn't work. You'll first have to say what the program does you know.
Even the Grep example does that.
