Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Python: Python

Learn Technical Writing from Unix Man in 10 Days

 

 

Python python RSS feed   Index | Next | Previous | View Threaded


xahlee at gmail

Apr 28, 2012, 2:55 PM

Post #1 of 17 (888 views)
Permalink
Learn Technical Writing from Unix Man in 10 Days

Learn Technical Writing from Unix Man in 10 Days

Quote from man apt-get:

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

Translation:

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

further readings:

• 〈The Idiocy of Computer Language Docs〉
http://xahlee.org/comp/idiocy_of_comp_lang.html

• 〈Why Open Source Documentation is of Low Quality〉
http://xahlee.org/UnixResource_dir/writ/gubni_papri.html

• 〈Python Documentation Problems〉
http://xahlee.org/perl-python/python_doc_index.html



DISAPPEARING URL IN DOC

so, i was reading man git. Quote:

Formatted and hyperlinked version of the latest git documentation
can
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:

• 〈Hackers: Dead Links and Human Compassion?〉
http://xahlee.org/comp/hacker_dead_links_and_compassion.html

• 〈Why Qi Lisp Fails and Clojure Succeeds〉
http://xahlee.org/UnixResource_dir/writ/qi_lang_marketing.html

• 〈unix: Hunspell Path Pain〉
http://xahlee.org/comp/hunspell_spell_path_pain.html

• 〈Python Doc URL disappearance〉
http://xahlee.org/perl-python/python_doc_url_disappearance.html

• 〈A Record of Frustration in IT Industry; Disappearing FSF URLs〉
http://xahlee.org/emacs/gnu_doc.html
--
http://mail.python.org/mailman/listinfo/python-list


lamialily at cleverpun

Apr 28, 2012, 3:36 PM

Post #2 of 17 (883 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

And what does this have to do with a multiplatform language like
Python? :P

~Temia
--
When on earth, do as the earthlings do.
--
http://mail.python.org/mailman/listinfo/python-list


rosuav at gmail

Apr 28, 2012, 4:30 PM

Post #3 of 17 (880 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Sun, Apr 29, 2012 at 8:36 AM, Temia Eszteri <lamialily [at] cleverpun> wrote:
> And what does this have to do with a multiplatform language like
> Python? :P

Nothing. Xah Lee is a professional troll. You can save yourself some
trouble by ignoring his posts altogether.

ChrisA
--
http://mail.python.org/mailman/listinfo/python-list


lamialily at cleverpun

Apr 28, 2012, 4:45 PM

Post #4 of 17 (894 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

>On Sun, Apr 29, 2012 at 8:36 AM, Temia Eszteri <lamialily [at] cleverpun> wrote:
>> And what does this have to do with a multiplatform language like
>> Python? :P
>
>Nothing. Xah Lee is a professional troll. You can save yourself some
>trouble by ignoring his posts altogether.
>
>ChrisA

Professional? He's boring! I wanted to see if I could poke him into
action. I know, I know, "don't feed the trolls." Just wanted to see if
he would actually come up with something interesting.

~Temia
--
When on earth, do as the earthlings do.
--
http://mail.python.org/mailman/listinfo/python-list


bahamutzero8825 at gmail

Apr 28, 2012, 4:54 PM

Post #5 of 17 (881 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On 4/28/2012 6:45 PM, Temia Eszteri wrote:
> Professional? He's boring!
I agree. Ranting Rick is much more entertaining (usually).

--
CPython 3.2.3/3.3.0a2 | Windows NT 6.1.7601.17790
--
http://mail.python.org/mailman/listinfo/python-list


steve+comp.lang.python at pearwood

Apr 28, 2012, 7:49 PM

Post #6 of 17 (876 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Sat, 28 Apr 2012 14:55:42 -0700, Xah Lee wrote:

> Learn Technical Writing from Unix Man in 10 Days
>
> Quote from man apt-get:
>
> remove
> remove is identical to install except that packages are
> removed
> instead of installed.


Do you also expect the documentation to define "except", "instead", "is",
"to" and "the"?

If you don't know what "install" and "remove" means, then you need an
English dictionary, not a technical manual.



--
Steven
--
http://mail.python.org/mailman/listinfo/python-list


cs at zip

Apr 28, 2012, 11:27 PM

Post #7 of 17 (871 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On 29Apr2012 02:49, Steven D'Aprano <steve+comp.lang.python [at] pearwood> wrote:
| On Sat, 28 Apr 2012 14:55:42 -0700, Xah Lee wrote:
| > Learn Technical Writing from Unix Man in 10 Days
| >
| > Quote from man apt-get:
| >
| > remove
| > remove is identical to install except that packages are
| > removed
| > instead of installed.
|
| Do you also expect the documentation to define "except", "instead", "is",
| "to" and "the"?

Of course he doesn't. But he may have expected something less trite from
the sentence, not that that would really make it more clear.

| If you don't know what "install" and "remove" means, then you need an
| English dictionary, not a technical manual.

Well, the sentence _is_ on par with several Haynes manuals which say
after the "remove/access motorcycle/car component": "installation is the
reverse of the disassembly". Fair enough.

However, I notice that my Haynes manuals on livestock do not include
this sentence in the butchering chapters:-)

Cheers,
--
Cameron Simpson <cs [at] zip> DoD#743
http://www.cskk.ezoshosting.com/cs/

Ride Free, Ride Nude! - David Jevans <jevans [at] apple>
--
http://mail.python.org/mailman/listinfo/python-list


research at johnohagan

Apr 29, 2012, 12:06 AM

Post #8 of 17 (877 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Sat, 28 Apr 2012 14:55:42 -0700 (PDT)
Xah Lee <xahlee [at] gmail> wrote:

> Learn Technical Writing from Unix Man in 10 Days
>
> Quote from man apt-get:
>
> remove
> remove is identical to install except that packages are
> removed
> instead of installed.
>
> Translation:
>
> kicking
> kicking is identical to kissing except that receiver is kicked
> instead of kissed.
>

That's funny - out of context. Maybe you're trying out material for a stand-up
comedy routine, but I'm sure you're aware that the sentence you quote sensibly
obviates repeating the semantics of "install", which have just been described
in detail in the immediately preceding paragraph. If it did repeat them,
wouldn't you mock the docs anyway, for redundancy?

Regards,
--
John
--
http://mail.python.org/mailman/listinfo/python-list


acm at muc

Apr 29, 2012, 2:24 AM

Post #9 of 17 (874 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

Hello, Xah.

In comp.emacs Xah Lee <xahlee [at] gmail> wrote:
> Learn Technical Writing from Unix Man in 10 Days

> Quote from man apt-get:

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

> Translation:

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

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.

> further readings:

[ .... ]

> DISAPPEARING URL IN DOC

> so, i was reading man git. Quote:

> Formatted and hyperlinked version of the latest git documentation
> can
> 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?

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

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

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.

> more records of careless dead link:

[ .... ]

--
Alan Mackenzie (Nuremberg, Germany).

--
http://mail.python.org/mailman/listinfo/python-list


kiuhnm03.4t.yahoo.it at mail

Apr 29, 2012, 5:21 AM

Post #10 of 17 (871 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On 4/28/2012 23:55, Xah Lee wrote:
> Learn Technical Writing from Unix Man in 10 Days
>
> Quote from man apt-get:
>
> remove
> remove is identical to install except that packages are
> removed
> instead of installed.
>
> Translation:
>
> kicking
> kicking is identical to kissing except that receiver is kicked
> instead of kissed.

Superficial as always.

Here's the part you misquoted:

--->
install
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,
unstable).

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
expression.

remove
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.
<---

Kiuhnm
--
http://mail.python.org/mailman/listinfo/python-list


jearl at notengoamigos

Apr 29, 2012, 7:43 PM

Post #11 of 17 (870 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Sat, Apr 28 2012, Steven D'Aprano wrote:

> On Sat, 28 Apr 2012 14:55:42 -0700, Xah Lee wrote:
>
>> Learn Technical Writing from Unix Man in 10 Days
>>
>> Quote from man apt-get:
>>
>> remove
>> remove is identical to install except that packages are
>> removed
>> instead of installed.
>
>
> Do you also expect the documentation to define "except", "instead", "is",
> "to" and "the"?
>
> If you don't know what "install" and "remove" means, then you need an
> English dictionary, not a technical manual.

It is considerably worse than that. If you look at what the
documentation for apt-get actually says, instead of just the badly
mangled version that Xah shares you would realize that the post was
basically a bald-face troll.

The rest of Xah's links in this particular article was even worse. For
the most part he was criticizing documentation flaws that have
disappeared years ago.

Heck, his criticism of Emacs' missing documentation has been fixed since
Emacs 21 (the Emacs developers are currently getting ready to release
Emacs 24). His criticism of git's documentation is also grossly
misleading. kernel.org still has the empty directories, but git-scm.org
has been the official home for git's documentation for years.

I am sure that the rest of the examples are just as ridiculous. I tend
to like Xah's writing. Heck, I even sent a few bucks his way as thanks
for his Emacs Lisp tutorials. However, that particular post was simply
ridiculous.

Jason
--
http://mail.python.org/mailman/listinfo/python-list


xahlee at gmail

Apr 29, 2012, 9:50 PM

Post #12 of 17 (873 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Apr 29, 7:43 pm, Jason Earl <je...@notengoamigos.org> wrote:
> On Sat, Apr 28 2012, Steven D'Aprano wrote:
> > On Sat, 28 Apr 2012 14:55:42 -0700, Xah Lee wrote:
>
> >> Learn Technical Writing from Unix Man in 10 Days
>
> >> Quote from man apt-get:
>
> >>     remove
> >>         remove is identical to install except that packages are
> >> removed
> >>         instead of installed.
>
> > Do you also expect the documentation to define "except", "instead", "is",
> > "to" and "the"?
>
> > If you don't know what "install" and "remove" means, then you need an
> > English dictionary, not a technical manual.
>
> It is considerably worse than that.  If you look at what the
> documentation for apt-get actually says, instead of just the badly
> mangled version that Xah shares you would realize that the post was
> basically a bald-face troll.
>
> The rest of Xah's links in this particular article was even worse.  For
> the most part he was criticizing documentation flaws that have
> disappeared years ago.
>
> Heck, his criticism of Emacs' missing documentation has been fixed since
> Emacs 21 (the Emacs developers are currently getting ready to release
> Emacs 24).  His criticism of git's documentation is also grossly
> misleading.  kernel.org still has the empty directories, but git-scm.org
> has been the official home for git's documentation for years.
>
> I am sure that the rest of the examples are just as ridiculous.  I tend
> to like Xah's writing.  Heck, I even sent a few bucks his way as thanks
> for his Emacs Lisp tutorials.  However, that particular post was simply
> ridiculous.
>
> Jason

jason, are you trolling me, or me you?



Xah
--
http://mail.python.org/mailman/listinfo/python-list


rosuav at gmail

Apr 29, 2012, 9:53 PM

Post #13 of 17 (871 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Mon, Apr 30, 2012 at 12:43 PM, Jason Earl <jearl [at] notengoamigos> wrote:
> It is considerably worse than that. If you look at what the
> documentation for apt-get actually says, instead of just the badly
> mangled version that Xah shares you would realize that the post was
> basically a bald-face troll.

Not only that, but a completely off-topic one... like a lot of his
trolls. What has 'man apt-get' to do with Python? For all I know, the
package may be written in Python, or the man page could be generated
on-the-fly by a Python script, but unless you say how it's relevant to
python-list/c.l.p, it's not obvious. Now, if that were 'man python'
that he's criticizing, then sure. But it's not.

ChrisA
--
http://mail.python.org/mailman/listinfo/python-list


lamialily at cleverpun

Apr 29, 2012, 10:06 PM

Post #14 of 17 (867 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

>jason, are you trolling me, or me you?
>
>?
>
> Xah

Depends on what you classify as "trolling" these days. In all honesty,
the original concept of trolling seems to have become a lost art, with
only a few people even knowing what the act actually was anymore, and
in its absence everyone seems to draw their own definitions and
conclusions of the term where it can be applied to whoever is
antagonistic towards them at the time.

In one definition, that being the one defined by common sense of
"getting a reaction out of people", you in fact succeeded rather well
by getting a reaction in general, though it was mostly mockery and
heckling. In another definitions calling trolling an attempt at
getting upset reactions specifically, I'd have to say there isn't so
much of that unless your inquiry into who's trolling whom was because
you felt as if you had been slighted by Jason's statement.

So really, it's a crapshoot at this point. Who's trolling whom indeed.

~Temia
--
When on earth, do as the earthlings do.
--
http://mail.python.org/mailman/listinfo/python-list


rosuav at gmail

Apr 29, 2012, 10:52 PM

Post #15 of 17 (873 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

On Mon, Apr 30, 2012 at 2:50 PM, Xah Lee <xahlee [at] gmail> wrote:
> jason, are you trolling me, or me you?

Am I Turing dreaming I am a machine, or a machine dreaming I am Turing?

Personally, I've never Turred.

ChrisA
--
http://mail.python.org/mailman/listinfo/python-list


neruyume at hotmail

Apr 29, 2012, 10:58 PM

Post #16 of 17 (875 views)
Permalink
RE: Learn Technical Writing from Unix Man in 10 Days [In reply to]

I did not sign up for this. ;_;


lamialily at cleverpun

Apr 29, 2012, 11:03 PM

Post #17 of 17 (872 views)
Permalink
Re: Learn Technical Writing from Unix Man in 10 Days [In reply to]

>On Mon, Apr 30, 2012 at 2:50 PM, Xah Lee <xahlee [at] gmail> wrote:
>> jason, are you trolling me, or me you?
>
>Am I Turing dreaming I am a machine, or a machine dreaming I am Turing?
>
>Personally, I've never Turred.
>
>ChrisA

Turing got a pretty shit deal for all the great things he did - odds
are a machine would look at his life and how it should've progressed a
lot better than we humans decided how it should've went.

So dream away, machine. Dream of a world we humans weren't smart
enough to live in.

~Temia
--
When on earth, do as the earthlings do.
--
http://mail.python.org/mailman/listinfo/python-list

Python python RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.