6 ms·

Yeah, what is the point of gnu info?

by ape4 13y ago

philsnow 13y ago
hypertext man pages ? what is it that people don't like about them ?
- ape4 13y ago
  Isn't there some way to get hypertext into man pages? Eg extend nroff. Then you don't have to have a parallel system.
  - 4ad 13y ago
    nroff isn't the problem, the pager is. I view manual pages in acme and they become very hypertexty. It's not perfect, as they weren't written with that in mind, but it's damn good.
  - clarry 13y ago
    You can use w3mman (it installs with the w3m package on OBSD) and you'll be able to follow manual xrefs. Html output with links can also be generated, see the afterbook man page linked above for an example.
mhurron 13y ago
NIH
teddyh 13y ago
From https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm... The preferred document format for the GNU system is the Texinfo formatting language. Every GNU package should (ideally) have documentation in Texinfo both for reference and for learners. Texinfo makes it possible to produce a good quality formatted book, using TeX, and to generate an Info file. It is also possible to generate HTML output from Texinfo source. [...] Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used. Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user. Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented—but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives. For example, each program in the GNU system probably ought to be documented in one manual; but this does not mean each program should have its own manual. That would be following the structure of the implementation, rather than the structure that helps the user understand. Instead, each manual should cover a coherent topic. For example, instead of a manual for diff and a manual for diff3, we have one manual for “comparison of files” which covers both of those programs, as well as cmp. By documenting these programs together, we can make the whole subject clearer. The manual which discusses a program should certainly document all of the program’s command-line options and all of its commands. It should give examples of their use. But don’t organize the manual as a list of features. Instead, organize it logically, by subtopics. Address the questions that a user will ask when thinking about the job that the program does. Don’t just tell the reader what each feature can do—say what jobs it is good for, and show how to use it for those jobs. Explain what is recommended usage, and what kinds of usage users should avoid. In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. The Bison manual (https://www.gnu.org/software/bison/manual/html_node/Concepts.html https://www.gnu.org/software/bison/manual/html_node/Concepts...) is a good example of this—please take a look at it to see what we mean. That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text. If necessary, add extra chapters at the beginning of the manual which are purely tutorial and cover the basics of the subject. These provide the framework for a beginner to understand the rest of the manual. The Bison manual (https://www.gnu.org/software/bison/manual/html_node/Concepts.html https://www.gnu.org/software/bison/manual/html_node/Concepts...) provides a good example of how to do this. To serve as a reference, a manual should have an Index that lists all the functions, variables, options, and important concepts that are part of the program. One combined Index should do for a short manual, but sometimes for a complex package it is better to use multiple indices. The Texinfo manual includes advice on preparing good index entries, see Making Index Entries(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Index-Entries.html https://www.gnu.org/software/texinfo/manual/texinfo/html_nod...) in GNU Texinfo, and see Defining the Entries of an Index(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Indexing-Commands.html https://www.gnu.org/software/texinfo/manual/texinfo/html_nod...) in GNU Texinfo. Don’t use Unix man pages as a model for how to write GNU documentation; most of them are terse, badly structured, and give inadequate explanation of the underlying concepts. (There are, of course, some exceptions.) Also, Unix man pages use a particular format which is different from what we use in GNU manuals. [...]
- csmuk 13y ago
  Unix manpages are fine. If you've read the GNU awk manual vs BSD awk, you'll understand what I mean. GNU awk manual is hundreds of pages long and serves only to confuse the user. Not only that, half of it is listing differences between GNU awk and other awks which is just mindnumbing. A fine case of cat -v. And don't get me started on glibc. The bit that pisses me off is: man awk (see info awk instead). I think they fixed that but it was a pain in the butt for years. Is it in man or is it in info? One tool for the job. Edit: cite your sources :) 1 - OpenBSD awk (6 pages if I print preview it): http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&s... 2 - GNU awk (330 pages if I print preview it): https://www.gnu.org/software/gawk/manual/gawk.html https://www.gnu.org/software/gawk/manual/gawk.html
  - teddyh 13y ago
    Even the document I cited conceded that there are some very good Unix man pages — BSD Awk may very well be one of many, I have not read it. It follows, logically, that there could be some very bad Info documentation manuals, and the GNU Awk manual may very well be one of many; I have not read it. This does not disprove the point the citation made; namely, that the Unix man page structure is unsuitable for many things since its structure tends to make people write manuals badly, and there is no place for the kind of introductions and tutorials that good manuals should contain. On the contrary, the man page format lends itself to very strict and terse reference documentation, which is not what I would call a “manual”, as such. Someone should perhaps do a study of which of the two formats seem to generate the better documentation. > The bit that pisses me off is: man awk (see info awk instead). I think they fixed that but it was a pain in the butt for years. Is it in man or is it in info? The official GNU system documentation is in Info. Now, the GNU system is meant to be compatible with Unix, and Unix uses man pages. And since many GNU tools were (and are) not actually developed to be used in the GNU system as such, but instead find their major use and development as parts of various Unix variants, it follows that most of them have Unix have man pages too. Since writing documentation is work, and writing duplicated documentation is even more work, the man pages for GNU tools are often overly terse, incomplete and/or out of date compared to the Info documentation, which is the official documentation. Some well-known exceptions exist, notably GNU Bash does not have any Info documentation, but instead has an (enormously long) Unix man page.
noselasd 13y ago
install pinfo , and you'll be able to read all the wonderful documentation instead of fighting with the GNU info frontend.

Yeah, what is the point of gnu info?

by ape4 13y ago

Yeah, what is the point of gnu info?

philsnow 13y ago

hypertext man pages ? what is it that people don't like about them ?

ape4 13y ago
Isn't there some way to get hypertext into man pages? Eg extend nroff. Then you don't have to have a parallel system.
- 4ad 13y ago
  nroff isn't the problem, the pager is. I view manual pages in acme and they become very hypertexty. It's not perfect, as they weren't written with that in mind, but it's damn good.
- clarry 13y ago
  You can use w3mman (it installs with the w3m package on OBSD) and you'll be able to follow manual xrefs. Html output with links can also be generated, see the afterbook man page linked above for an example.

mhurron 13y ago

NIH

teddyh 13y ago

From https://www.gnu.org/prep/standards/html_node/GNU-Manuals.html https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm... The preferred document format for the GNU system is the Texinfo formatting language. Every GNU package should (ideally) have documentation in Texinfo both for reference and for learners. Texinfo makes it possible to produce a good quality formatted book, using TeX, and to generate an Info file. It is also possible to generate HTML output from Texinfo source. [...] Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used. Programmers tend to carry over the structure of the program as the structure for its documentation. But this structure is not necessarily good for explaining how to use the program; it may be irrelevant and confusing for a user. Instead, the right way to structure documentation is according to the concepts and questions that a user will have in mind when reading it. This principle applies at every level, from the lowest (ordering sentences in a paragraph) to the highest (ordering of chapter topics within the manual). Sometimes this structure of ideas matches the structure of the implementation of the software being documented—but often they are different. An important part of learning to write good documentation is to learn to notice when you have unthinkingly structured the documentation like the implementation, stop yourself, and look for better alternatives. For example, each program in the GNU system probably ought to be documented in one manual; but this does not mean each program should have its own manual. That would be following the structure of the implementation, rather than the structure that helps the user understand. Instead, each manual should cover a coherent topic. For example, instead of a manual for diff and a manual for diff3, we have one manual for “comparison of files” which covers both of those programs, as well as cmp. By documenting these programs together, we can make the whole subject clearer. The manual which discusses a program should certainly document all of the program’s command-line options and all of its commands. It should give examples of their use. But don’t organize the manual as a list of features. Instead, organize it logically, by subtopics. Address the questions that a user will ask when thinking about the job that the program does. Don’t just tell the reader what each feature can do—say what jobs it is good for, and show how to use it for those jobs. Explain what is recommended usage, and what kinds of usage users should avoid. In general, a GNU manual should serve both as tutorial and reference. It should be set up for convenient access to each topic through Info, and for reading straight through (appendixes aside). A GNU manual should give a good introduction to a beginner reading through from the start, and should also provide all the details that hackers want. The Bison manual (https://www.gnu.org/software/bison/manual/html_node/Concepts.html https://www.gnu.org/software/bison/manual/html_node/Concepts...) is a good example of this—please take a look at it to see what we mean. That is not as hard as it first sounds. Arrange each chapter as a logical breakdown of its topic, but order the sections, and write their text, so that reading the chapter straight through makes sense. Do likewise when structuring the book into chapters, and when structuring a section into paragraphs. The watchword is, at each point, address the most fundamental and important issue raised by the preceding text. If necessary, add extra chapters at the beginning of the manual which are purely tutorial and cover the basics of the subject. These provide the framework for a beginner to understand the rest of the manual. The Bison manual (https://www.gnu.org/software/bison/manual/html_node/Concepts.html https://www.gnu.org/software/bison/manual/html_node/Concepts...) provides a good example of how to do this. To serve as a reference, a manual should have an Index that lists all the functions, variables, options, and important concepts that are part of the program. One combined Index should do for a short manual, but sometimes for a complex package it is better to use multiple indices. The Texinfo manual includes advice on preparing good index entries, see Making Index Entries(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Index-Entries.html https://www.gnu.org/software/texinfo/manual/texinfo/html_nod...) in GNU Texinfo, and see Defining the Entries of an Index(https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Indexing-Commands.html https://www.gnu.org/software/texinfo/manual/texinfo/html_nod...) in GNU Texinfo. Don’t use Unix man pages as a model for how to write GNU documentation; most of them are terse, badly structured, and give inadequate explanation of the underlying concepts. (There are, of course, some exceptions.) Also, Unix man pages use a particular format which is different from what we use in GNU manuals. [...]

csmuk 13y ago
Unix manpages are fine. If you've read the GNU awk manual vs BSD awk, you'll understand what I mean. GNU awk manual is hundreds of pages long and serves only to confuse the user. Not only that, half of it is listing differences between GNU awk and other awks which is just mindnumbing. A fine case of cat -v. And don't get me started on glibc. The bit that pisses me off is: man awk (see info awk instead). I think they fixed that but it was a pain in the butt for years. Is it in man or is it in info? One tool for the job. Edit: cite your sources :) 1 - OpenBSD awk (6 pages if I print preview it): http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html http://www.openbsd.org/cgi-bin/man.cgi?query=awk&apropos=0&s... 2 - GNU awk (330 pages if I print preview it): https://www.gnu.org/software/gawk/manual/gawk.html https://www.gnu.org/software/gawk/manual/gawk.html
- teddyh 13y ago
  Even the document I cited conceded that there are some very good Unix man pages — BSD Awk may very well be one of many, I have not read it. It follows, logically, that there could be some very bad Info documentation manuals, and the GNU Awk manual may very well be one of many; I have not read it. This does not disprove the point the citation made; namely, that the Unix man page structure is unsuitable for many things since its structure tends to make people write manuals badly, and there is no place for the kind of introductions and tutorials that good manuals should contain. On the contrary, the man page format lends itself to very strict and terse reference documentation, which is not what I would call a “manual”, as such. Someone should perhaps do a study of which of the two formats seem to generate the better documentation. > The bit that pisses me off is: man awk (see info awk instead). I think they fixed that but it was a pain in the butt for years. Is it in man or is it in info? The official GNU system documentation is in Info. Now, the GNU system is meant to be compatible with Unix, and Unix uses man pages. And since many GNU tools were (and are) not actually developed to be used in the GNU system as such, but instead find their major use and development as parts of various Unix variants, it follows that most of them have Unix have man pages too. Since writing documentation is work, and writing duplicated documentation is even more work, the man pages for GNU tools are often overly terse, incomplete and/or out of date compared to the Info documentation, which is the official documentation. Some well-known exceptions exist, notably GNU Bash does not have any Info documentation, but instead has an (enormously long) Unix man page.

noselasd 13y ago

install pinfo , and you'll be able to read all the wonderful documentation instead of fighting with the GNU info frontend.