Messages in this thread | | | Date | Wed, 4 Aug 1999 15:29:41 -0400 (EDT) | From | David Forrest <> | Subject | Re: info format (was Re: Linux 2.2.11pre4) |
| |
On 4 Aug 1999, Andreas Schwab wrote:
> rct@gherkin.sa.wlk.com (Bob_Tracy) writes: ... > |> is reasonable and appropriate, but I STILL WANT THE #$%@! man PAGE, and > |> it should be kept up to date. Agree - man is far more general and reliable than info. ... > documentation. Remember that all those things are done *voluntarily*, and > if nobody wants to do it, then it won't be done, period. Also agree, but the system seems set up to discourage volunteerism.
GNU's coding standard: http://www.gnu.org/prep/standards_37.html#SEC37 is very down on man pages, and even recommends rejecting man pages volunteered by others.
But the man system seems more reliable than the info system (due to the makewhatis and the use of plain directories rather than info/dir files), and better synopsis format. The two main programs most intimately involved in the documentation are 'info' and 'texinfo' -- info.info doesn't seem to follow the coding standard about referring to the maintainer, and is unhelpful for setting up the info system. Texinfo is not broken, and the stand-alone info program is not broken, what is broken is the setup and configuration of the /*/info/(dir|*) structure and the environmental variables, which doesn't seem to be documented anywhere.
I think a nice thing would be to change the coding standard to add a 'man' node to the texinfo documentation for a program. It would help the info writers make a consistent summary-type thing, and some interested person could write a stripper program to build a man page from that node.
Really, this discussion belongs somewhere else, maybe on help-gnu-utils@gnu.org or bug-gnu-utils@gnu.org, help-texinfo@gnu.org or bug-texinfo.gnu.org. Do those seem like the right places for us to complain/help?
Just my 2 cents... -- Dave Forrest dforrest@virginia.edu (804)-296-7283 http://www.people.virginia.edu/~drf5n/
- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
| |