Prev: Remove certain characters in a filename
Next: x12a403
From: Seebs on 2 Feb 2010 09:50
On 2010-02-02, Ivan Shmakov <ivan(a)main.uusia.org> wrote:
> Doesn't M-x info RET d m gcc RET give you something where ?s
> msoft-float RET n s RET? gets you to the very same option?

I have no clue.

I use about fifteen programs in which /foo<return> yields a search for
foo. I am not very motivated to learn another interface...

> Agreed. But what'd be the purpose of keeping the separate Man
> reference when there's already one in the Info manual?

Well-documented, standard, interface for quick references.

Why are there quick reference cards when all the information on them is
presumably in a book somewhere? Why are there both formal specifications
and books about topics?

If you have two wildly different documents, it is often better to provide
them separately -- and each can then benefit from design choices ideally
suited to its intended use.

> S> Tcl gets its own section.

> So, a Man section per programming language is the way to go?

Not necessarily.

> So does Vim, and Less, at least when most of the today ?computer
> users? are concerned.

True. And I'm not a big fan of less, for that reason. I'm okay with
vi because I expect it, but I recognize that it's an expert-friendly tool
rather than a newbie-friendly tool.

> IIRC, there was no single cross-platform Man implementation?

So what? Implementation isn't what you standardize. No one cares
*how* read(2) works, the point is that you can call read(2) on a file
descriptor and get basically the same behavior across a large number
of completely unrelated implementations... And you can type "man 2 read"
and get basically the same behavior across a large number of essentially
unrelated implementations.

> S> So write the tutorial AFTER you have written the basic manual.

> Once again, I agree with that. But after the latter is fully
> embedded into the former, I see no reason to maintain the latter
> separately.

But it should NOT be embedded into the former. They're fundamentally
different things. They have different technical requirements. Trying to
coerce one into a format suited to the other makes for bad usability.

> That being said, Docbook has the facilities to support producing
> both the printable document, and the specially marked excerpts
> from it as the Man pages. But I surely do not want to propose
> it for the GNU standard documentation platform.

The idea of a single standard documentation platform is probably a poor
one. Different purposes suggest different tools. A single standard
documentation platform is about as good idea as a single standard programming
language which everything must be written in.

> Once one's given infinite time to implement it, this advice
> seems reasonable.

Even if you have a short amount of time, make a tutorial which is
structured and built to be a good tutorial, and a reference manual which
is structured and built to be a good reference manual. This does not take
more time than trying to make a single be-all/end-all document, and produces
better results for both purposes.

Past this... I think at this point I should just drop this. I'm unlikely
to convince you, because your goals and interests are so very different from
mine. Fundamentally, all engineering questions are contingent on your
goals and purposes. For my purposes, the info system is useless. Maybe
it works for yours. I don't think arguing about it is very productive, and
I apologize for my tone; this is an issue I feel pretty strongly about, as
you may have guessed.

-s
--
Copyright 2010, all wrongs reversed. Peter Seebach / usenet-nospam(a)seebs.net
http://www.seebs.net/log/ <-- lawsuits, religion, and funny pictures
http://en.wikipedia.org/wiki/Fair_Game_(Scientology) <-- get educated!
From: Seebs on 2 Feb 2010 09:53
On 2010-02-02, Chris F.A. Johnson <cfajohnson(a)gmail.com> wrote:
> On 2010-02-02, Ivan Shmakov wrote:
> ...
>> Agreed. But what'd be the purpose of keeping the separate Man
>> reference when there's already one in the Info manual?

> What's the purpose of a separate Info manual when there's a
> perfectly good man page?

The info manual would be a good place to have information which isn't really
suited to the man page. For instance, for gcc, it would make a lot of sense
to have detailed documentation of the C language, as well as some variants
(such as GNU C)... But not in the gcc man page. Similarly, it would make a
lot of sense for the manual for gas to describe how you invoke gas, what
arguments it takes, and so on, but not so much for it to describe the detailed
syntax of the assembler across a dozen architectures.

I think it very much makes sense to have multiple manuals, because "how do I
use this program" and "how do I write code in the language this program
compiles" are fundamentally separate questions. Perl does a pretty good
job of this, with a man page for the program itself, and then a number of
man pages describing various other features. However, it wouldn't be
unreasonable to argue that the other features would be just as well served by
being documented in a single coherent document not served up as a man page.
(As I recall, POD also addresses the "man pages and other formats" question,
and does so quite well.)

-s
--
Copyright 2010, all wrongs reversed. Peter Seebach / usenet-nospam(a)seebs.net
http://www.seebs.net/log/ <-- lawsuits, religion, and funny pictures
http://en.wikipedia.org/wiki/Fair_Game_(Scientology) <-- get educated!
From: Ivan Shmakov on 2 Feb 2010 11:53
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

>>>>> "S" == Seebs <usenet-nospam(a)seebs.net> writes:
>>>>> "IS" == Ivan Shmakov <ivan(a)main.uusia.org> wrote:

IS> Doesn't M-x info RET d m gcc RET give you something where ?s
IS> msoft-float RET n s RET? gets you to the very same option?

S> I have no clue.

“M-x info RET” starts Info (switches to the “*info*” buffer)
within Emacs. “C-h i” does the same, BTW.

“d” brings you the “directory” node, from where “m gcc RET”
chooses the “gcc” entry.

“s msoft-float RET” starts the search.

“n” skips the section.

“s RET” repeats the search.

While at Info, “d m gcc RET” is roughly an equivalent to
$ man gcc, while “s msoft-float RET” is a direct equivalent for
“/ msoft-float RET”. Instead of “n” (for “next”) there's
“s RET”, while Info's “n” has no direct equivalent in the pagers
I know.

... Isn't it simple?

Then, there also “p” (previous node), “u” (“up”, i. e. parent
node) and “l” (“last”, i. e., previously visited node), which
make the reading of Info files even more a pleasant experience.

S> I use about fifteen programs in which /foo<return> yields a search
S> for foo. I am not very motivated to learn another interface...

Do you use / to search the Bash history as well?

Will / grep over the article in Slrn? or will it grep over the
group?

IS> Agreed. But what'd be the purpose of keeping the separate Man
IS> reference when there's already one in the Info manual?

S> Well-documented, standard, interface for quick references.

[...]

S> Tcl gets its own section.

IS> So, a Man section per programming language is the way to go?

S> Not necessarily.

And how then? Where the reference for the Octave functions
should go? And where should the one for Scheme ones go? Then,
the same for GNU R and GSL, GNU MP and M4? and Autoconf?

How should the Emacs functions and macros be documented? Should
there be a Man page per function?

Given a right angle to see, the Info way of accessing the
documentation may be observed as a generalization of the Man
one, with better ways to tie the related parts to each other.

IS> So does Vim, and Less, at least when most of the today ?computer
IS> users? are concerned.

S> True. And I'm not a big fan of less, for that reason.

Nice.

S> I'm okay with vi because I expect it, but I recognize that it's an
S> expert-friendly tool rather than a newbie-friendly tool.

It has been observed that any tool, when used improperly, will
become an obstacle instead of being a help.

However, there're different types of newbies, actually. And I
assume that it's my work to help the students become the “right”
newbies, to which Less, Vim and Emacs are in fact friendly.

IS> IIRC, there was no single cross-platform Man implementation?

S> So what? Implementation isn't what you standardize. No one cares
S> *how* read(2) works, the point is that you can call read(2) on a
S> file descriptor and get basically the same behavior across a large
S> number of completely unrelated implementations... And you can type
S> "man 2 read" and get basically the same behavior across a large
S> number of essentially unrelated implementations.

Well, yes.

OTOH:

$ (for i in waterlily gray cylon earth theory th3 ip[...] ; do \
ssh "$i" LC_ALL=C man 2 read ; \
done)
No manual entry for read in section 2
No manual entry for read in section 2
ivan@[...]'s password: [...]
READ(2) Linux Programmer's Manual READ(2)
[...]
Linux 2007-11-15 READ(2)
No manual entry for read in section 2
No manual entry for read in section 2
No manual entry for read in section 2
No manual entry for read in section 2
$

So, given this particular case of related systems (all of the
systems above are under my control currently), the observed
consistency is rather unhelpful. (I've assumed control of cylon
fairly recently and haven't checked the packages installed yet.)

IIRC, there were never a complaint on the lack of the section 2
manual pages from the users.

S> So write the tutorial AFTER you have written the basic manual.

IS> Once again, I agree with that. But after the latter is fully
IS> embedded into the former, I see no reason to maintain the latter
IS> separately.

S> But it should NOT be embedded into the former. They're
S> fundamentally different things. They have different technical
S> requirements. Trying to coerce one into a format suited to the
S> other makes for bad usability.

I doubt so. Nevertheless, it solves the problem of
synchronisation of the reference with the manual.

... Quite a while ago, there was a computer scientist who
proposed a source code and documentation synchronisation
solution, which was based on twisting both into a single file.
To my mind, it has failed to catch. But was it that wrong?

IS> That being said, Docbook has the facilities to support producing
IS> both the printable document, and the specially marked excerpts from
IS> it as the Man pages. But I surely do not want to propose it for
IS> the GNU standard documentation platform.

S> The idea of a single standard documentation platform is probably a
S> poor one. Different purposes suggest different tools.

One can use different tools to process XML, much the same way
that one can use a plethora of tools to process plain text.
(But note that complex XML is much easier to process than
complex plain text.)

Unfortunately, I cannot say the same about either *roff or
Texinfo. (That's why I write my Man pages in Docbook.)

S> A single standard documentation platform is about as good idea as a
S> single standard programming language which everything must be
S> written in.

There's at least one universal typesetting platform which, by a
coincidence, is a programming language. Or, rather, the former
is LaTeX, while the latter is TeX. And Texinfo bears
significantly from TeX-based systems.

[...]

S> Past this... I think at this point I should just drop this. I'm
S> unlikely to convince you, because your goals and interests are so
S> very different from mine. Fundamentally, all engineering questions
S> are contingent on your goals and purposes. For my purposes, the
S> info system is useless. Maybe it works for yours. I don't think
S> arguing about it is very productive, and I apologize for my tone;

The tone is okay.

Well, I'd say that the discussions of this sort happen to
somehow grow much more hot when done in my native language.
Thank you for not going as far as the native speakers of my also
native language will typically go.

S> this is an issue I feel pretty strongly about, as you may have
S> guessed.

So do I.

But then, I've managed to learn on how to use both Info and Man,
as I see appropriate. Somehow, I think it gives me an, however
slight, advantage?

PS. I think I should post a small summary of the features of the
Texinfo system which, in my opinion, Man is lacking and why I
think of them as important.

- --
FSF associate member #7257
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iEYEARECAAYFAktoWJ8ACgkQMBO2oCMOM0qAkACgh4eWDgUY/mMxEb0B1EAlVyTQ
MhUAnR381rqHcLY6EPYHgMa4c/gTpTQx
=wH2t
-----END PGP SIGNATURE-----
From: Jerry Peters on 2 Feb 2010 16:46
Ivan Shmakov <ivan(a)main.uusia.org> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
>>>>>> "S" == Seebs <usenet-nospam(a)seebs.net> writes:
>>>>>> "IS" == Ivan Shmakov <ivan(a)main.uusia.org> wrote:
>
> IS> Doesn't M-x info RET d m gcc RET give you something where ?s
> IS> msoft-float RET n s RET? gets you to the very same option?
>
> S> I have no clue.
>
> ?M-x info RET? starts Info (switches to the ?*info*? buffer)
> within Emacs. ?C-h i? does the same, BTW.
>
> ?d? brings you the ?directory? node, from where ?m gcc RET?
> chooses the ?gcc? entry.
>
> ?s msoft-float RET? starts the search.
>
> ?n? skips the section.
>
> ?s RET? repeats the search.
>
> While at Info, ?d m gcc RET? is roughly an equivalent to
> $ man gcc, while ?s msoft-float RET? is a direct equivalent for
> ?/ msoft-float RET?. Instead of ?n? (for ?next?) there's
> ?s RET?, while Info's ?n? has no direct equivalent in the pagers
> I know.
>
> ... Isn't it simple?
>
> Then, there also ?p? (previous node), ?u? (?up?, i. e. parent
> node) and ?l? (?last?, i. e., previously visited node), which
> make the reading of Info files even more a pleasant experience.

Not if you're not an emacs user. For when I have to use the info
abomination, I use tkinfo; it's not perfect, but just about anything
is better than having to use emacs key bindings.

I agree with Seebs, it's much easier to type "man <whatever>"
"/-x" to find information on option "x" than to wade through an index.
For concepts the index is even worse, if I can't guess what the author
called it, I have to search through the toc/index *hoping* something
sticks out. With man I just do a search for some of the words.

Jerry
From: Tony Sequeira on 2 Feb 2010 17:08
Jerry Peters wrote:

[...]

> Not if you're not an emacs user. For when I have to use the info
> abomination, I use tkinfo; it's not perfect, but just about anything
> is better than having to use emacs key bindings.

Thanks for that, tkinfo makes life easier, not much, but some. I'd just
about given up on the info documentation.

> I agree with Seebs, it's much easier to type "man <whatever>"

+1

> "/-x" to find information on option "x" than to wade through an index.
> For concepts the index is even worse, if I can't guess what the author
> called it, I have to search through the toc/index *hoping* something
> sticks out. With man I just do a search for some of the words.
>
> Jerry

--
S. Anthony Sequeira
++
Yes, we have consensus that we need 64 bit support. :-)
-- Larry Wall in <199710291922.LAA07101(a)wall.org>
++
First  |  Prev  |  Next  |  Last
Pages: 1 2 3 4 5 6 7
Prev: Remove certain characters in a filename
Next: x12a403