Learn Technical Writing from Unix Man in 10 Days

Do you have a question? Post it now! No Registration Necessary.  Now with pictures!

Threaded View
Learn Technical Writing from Unix Man in 10 Days

Quote from man apt-get:

        remove is identical to install except that packages are
        instead of installed.


        kicking is identical to kissing except that receiver is kicked
        instead of kissed.

further readings:

=E2=80=A280=88The Idiocy of Computer Language Docs=E3=80=89

=E2=80=A280=88Why Open Source Documentation is of Low Quality=E3=80=89

=E2=80=A280=88Python Documentation Problems=E3=80=89


so, i was reading man git. Quote:

    Formatted and hyperlinked version of the latest git documentation
    be viewed at http://www.kernel.org/pub/software/scm/git/docs /.

but if you go to that url, it shows a list of over one hundred fourty
empty dirs.

I guess unix/linux idiots can't be bothered to have correct
documentation. Inability to write is one thing, but they are unable to
maintain a link or update doc?

does this ever happens to Apple's docs? If it did, i don't ever recall
seeing it from 18 years of using Mac.

more records of careless dead link:

=E2=80=A280=88Hackers: Dead Links and Human Compassion?=E3=80=89

=E2=80=A280=88Why Qi Lisp Fails and Clojure Succeeds=E3=80=89

=E2=80=A280=88unix: Hunspell Path Pain=E3=80=89

=E2=80=A280=88Python Doc URL disappearance=E3=80=89

=E2=80=A280=88A Record of Frustration in IT Industry; Disappearing FSF=

Re: Learn Technical Writing from Unix Man in 10 Days

Hello, Xah.

Quoted text here. Click to load it

Ha ha ha ha!!

You don't need to go as far as apt-get to see this.  Even worse is C-h f
car in Emacs.  Imagine it before the last paragraph got added.  This only
happened after a fairly long thread on emacs-devel.

There are far too many man pages which are suboptimal, to say the least.

Quoted text here. Click to load it

[ .... ]

Quoted text here. Click to load it

Maintaining links is actually quite hard.  After the struggle to document
"remove", one typically has insufficient energy left over to check all
the links.

Quoted text here. Click to load it

Have you ever tried to set up CUPS, the printing system?  At one point,
you're supposed to enter the "URI" of the printer, without any explanation
of what the URI of a local printer is.  At another point you're prompted
to enter "Name".  Name of what?  If you click on the "help", you get
taken to a search box, not proper docs.  Typing "name" into the search
box isn't useful.  And so it goes on.

CUPS is an Apple product.

Quoted text here. Click to load it

[ .... ]

Alan Mackenzie (Nuremberg, Germany).

Re: Learn Technical Writing from Unix Man in 10 Days

On 4/28/2012 23:55, Xah Lee wrote:
Quoted text here. Click to load it

Superficial as always.

Here's the part you misquoted:

    install is followed by one or more packages desired for
    installation or upgrading. Each package is a package name, not a
    fully qualified filename (for instance, in a Debian GNU/Linux
    system, libc6 would be the argument provided, not
    libc6_1.9.6-2.deb). All packages required by the package(s)
    specified for installation will also be retrieved and installed.
    The /etc/apt/sources.list file is used to locate the desired
    packages. If a hyphen is appended to the package name (with no
    intervening space), the identified package will be removed if it is
    installed. Similarly a plus sign can be used to designate a package
    to install. These latter features may be used to override decisions
    made by apt-get's conflict resolution system.

    A specific version of a package can be selected for installation by
    following the package name with an equals and the version of the
    package to select. This will cause that version to be located and
    selected for install. Alternatively a specific distribution can be
    selected by following the package name with a slash and the version
    of the distribution or the Archive name (stable, testing,

    Both of the version selection mechanisms can downgrade packages and
    must be used with care.

    This is also the target to use if you want to upgrade one or more
    already-installed packages without upgrading every package you have
    on your system. Unlike the "upgrade" target, which installs the
    newest version of all currently installed packages, "install" will
    install the newest version of only the package(s) specified. Simply
    provide the name of the package(s) you wish to upgrade, and if a
    newer version is available, it (and its dependencies, as described
    above) will be downloaded and installed.

    Finally, the apt_preferences(5) mechanism allows you to create an
    alternative installation policy for individual packages.

    If no package matches the given expression and the expression
    contains one of '.', '?' or '*' then it is assumed to be a POSIX
    regular expression, and it is applied to all package names in the
    database. Any matches are then installed (or removed). Note that
    matching is done by substring so 'lo.*' matches 'how-lo' and
    'lowest'. If this is undesired, anchor the regular expression with
    a '^' or '$' character, or create a more specific regular

    remove is identical to install except that packages are removed
    instead of installed. Note the removing a package leaves its
    configuration files in system. If a plus sign is appended to the
    package name (with no intervening space), the identified package
    will be installed instead of removed.


Site Timeline