On Tue, Aug 12, 2008 at 05:45:08PM +0100, Thomas Adam wrote: > I will state at this point, categorically, that although being true > to GNU's roots is nice, I am dead against texinfo pages -- *no* one > actually reads them; heck, the existing info viewer is an > abomination,
I think it would be more accurate to say that primarily Emacs users read them. I like them because (most manuals) have command and subject indexes, and the browsers have a "back button" (l) to go to the previous page, and because the search functions (C-s and C-M-s) can search beyond the current page. The man format doesn't have indexes, and HTML doesn't support searching across a multi-page document. I also use manpages, but for *quick reference* -- not as a manual, but as a refresher to remind me of the name of a switch or command. I *like* the way GNU coreutils has quick reference content in manpages (e.g. cp.1) and a *separate* manual that describes the package in detail. I prefer this to bash's manpage, where I feel overwhelmed; or to perl's manpages, where it takes me ages to find the right one. >> and future releases might include one of those shell-of-a-manpages >> that simply refer the reader to the Texinfo documentation. Surely >> that's enough to scare a few of you into volunteering? ;) I'd prefer the screen manpage to simply have a one-line synopsis, a two-paragraph description and then a one-line (.TP) description of each switch and :command. >> To my mind, unifying on a single source format would be the best >> long-term approach, rather than having two manuals maintained. So >> far, the approach that makes the most sense to me is to use the >> Texinfo as the source document, generating the manpage with >> texi2pod.pl (see Wget's Texinfo documentation for an understanding >> of this; note that, even with texi2pod.pl, however, Wget's man page >> is still very much inferior to their Texinfo counterparts: only a >> small portion is translated into the man page). However, for Screen >> this would require texi2pod.pl to be modified to allow arbitrary >> sections to be transmitted (it only allows the standard ones, >> currently). > > Or use asciidoc or txt2tags, etc. Do those have good support for large manuals, with cross-referencing and multiple indexes within the document? My memory of them is that they implement headings, literal blocks and emphatic/strong text; if you want anything more, too bad. > I disagree. Having one manpage for screen, and another for the > screenrc is in keeping with "tradition" -- splitting this mythical > screen(1) manpage up would only alienate its use -- how would/are > people supposed to know/remember which manpage to refer to? I'm not bothered by having a second manpage for screenrc; but how do you decide what should go in it? Should :commands be described in screen(1) or screenrc(5)? They can be used both interactively and in .screenrc. The same applies for the description of string escapes. _______________________________________________ screen-users mailing list screen-users@gnu.org http://lists.gnu.org/mailman/listinfo/screen-users
