Women in Technology

Hear us Roar



Article:
  FreeBSD for Linux Users
Subject:   Documentation
Date:   2004-11-12 08:54:34
From:   sukrutikves
Linux utilities do not actively maintain man pages. They have their own "info" documents which contain much detailed and better organized information.


(For example while bash man page is over 4000 lines, bash info starts with a two page index).


And most of the distributions come with a nice utility called "pinfo" which will allow lynx like (nicer and easier) navigation of info pages.


Extract from ls man page:


The full documentation for ls is maintained as a Texinfo
manual. If the info and ls programs are properly installed
at your site, the command


info ls


should give you access to the complete manual.


Corrosponding info part:


`-F'
`--classify'
`--indicator-style=classify'
Append a character to each file name indicating the file type.
Also, for regular files that are executable, append `*'.
The file type indicators are `/' for directories, `@'
for symbolic links, `|' for FIFOs, `=' for sockets,
and nothing for regular files.

Main Topics Newest First

Showing messages 1 through 3 of 3.

  • re: Documentation
    2004-11-12 08:56:25  sukrutikves [View]

    Sorry for the wide comment. There was no preview or edit option.

    I'd be glad if a moderator breaks my lines. :)
  • Documentation
    2004-11-15 19:01:52  pappires [View]

    By "Linux utilities" you mean GNU utilities, right?


    I don't know why GNU sabotages manpages. While I understand that interactive documents may be useful for seeking specific information in several thousand lines of documentation, simply replacing manpages with .info files has clear disadvantages.


    First of all, info(1) is not available everywhere. While this is especially true for commercial unices, it may well apply to many open source systems, even in the Linux camp. Also, not every application in a generic unix box is a GNU application, and its documentation may not be in GNU's texinfo format. BSDs generally include info(1) and .info files for the GNU utilities they use, but programs like ls(1), awk(1) or make(1) are not GNU applications in BSD systems -- actually, GNU didn't even exist when they and their manual entries were written. Although, by definition, "GNU's not Unix", if it is Unix-like and, most especially, if it want its users to use it as they would use any other Unix system, it should allow its users to retrieve relevant information with manpages.


    While there is still a handful of other serious problems with texinfo, when intended to replace manpages, I will go back to one of your first statements, and say that I disagree that .info documents provide for more well organized information. Being "navigable" doesn't at all mean that a document is well organized, and much less does it mean that it is well written and can be easily read. Even the most powerful tool can become useless or wasteful in the hands of an inept writer, and I am pretty sure that I am not the only one that knows lots of plain text documents that beat many full-featured hypertext documents regarding the same information, not only in clearness, cleverness and accuracy, but even in visual cleanness.


    Best regards.


        Paulo

  • alternative man pages
    2004-11-21 07:38:25  scotttsai [View]

    Modern linux distros also ship the POSIX/SUS specifications as manpages.
    ex: man 1p ls, excerpt

    -F Do not follow symbolic links named as operands unless the -H or
    -L options are specified. Write a slash ( ’/’ ) immediately
    after each pathname that is a directory, an asterisk ( ’*’ )
    after each that is executable, a vertical bar ( ’|’ ) after each
    that is a FIFO, and an at sign ( ’@’ ) after each that is a sym-
    bolic link. For other file types, other symbols may be written.