[clug] Man pages.

Scott Ferguson scott.ferguson.clug at gmail.com
Mon Jul 27 01:40:38 UTC 2015


On 27/07/15 10:30, Ivan Lazar Miljenovic wrote:
> On 27 July 2015 at 08:48, Bob Edwards <Robert.Edwards at anu.edu.au> wrote:
>> On 24/07/15 19:37, Bryan Kilgallin wrote:
>>>
>>> Andrew wrote:
>>>
>>>> These toolkits are now all developed on github and it begs
>>>> the question if I should use something else to write the documentation
>>>> (markdown?) and then create the man page from it via some tool.
>>>
>>>
>>> Please test text for readability, using software such as the following
>>> site.
>>> http://www.online-utility.org/english/readability_test_and_improve.jsp
>>>
>>
>> I tested that paragraph at that website and it says it should be
>> comprehensible ("understood") by someone with between 7.75 and 9.71
>> years of formal education (depending upon which "index" you subscribe
>> to). So, someone with a (basic) Yr 10 certificate.
>>
>> What level of education do _you_ think posts to this list should be
>> striving for?
>>
>> I really can't see anyone methodically (sorry...) testing each post
>> to this (or any other) list for readability at such a site before
>> hitting the "Send" button...

Well... 'I' might, but to what point? (see further down).

> 
> I thought Bryan was referring to the text of the man pages, rather
> than posts to this list.
> 
> 
I guessed there was several possibilities, that one "seemed" the most
likely.

I then tried parsing his post through 'style'... however neither
Kincaid, LRI, Coleman-Liau, Flesch, Gunning-Fog, Lix, nor SMOG test
whether the input makes sense.

'diction' didn't help either :(

If he was referring to the content of man pages. Determining the
readability of man pages (or any technical documentation) is not as
simple as assessing it by readability tests designed for non-technical
writing - for obvious reasons.

http://www.malloc47.com/blog/man-page-readability/
http://liw.fi/manpages/

Take the example "ideal" for a man page in the last reference and test
it's readability.

echo "stuff" | style -L en_GB
readability grades:
        Kincaid: 7.1
        ARI: 7.4
        Coleman-Liau: 8.0
        Flesch Index: 79.3/100
        Fog Index: 8.5
        Lix: 41.7 = school year 7
        SMOG-Grading: 6.2
sentence info:
        238 characters
        59 words, average length 4.03 characters = 1.27 syllables
        3 sentences, average length 19.7 words
        66% (2) short sentences (at most 15 words)
        33% (1) long sentences (at least 30 words)
        1 paragraphs, average length 3.0 sentences
        0% (0) questions
        33% (1) passive sentences
        longest sent 40 wds at sent 1; shortest sent 4 wds at sent 3
word usage:
        verb types:
        to be (1) auxiliary (0)
        types as % of total:
        conjunctions 0% (0) pronouns 0% (0) prepositions 7% (4)
        nominalizations 2% (1)
sentence beginnings:
        pronoun (0) interrogative pronoun (0) article (0)
        subordinating conjunction (0) conjunction (0) preposition (0)

echo "stuff" | diction
.SH NAME
corrupt \- modify files by randomly changing bits
.SH SYNOPSIS
.B corrupt
[\fB\-n\fR \fIBITS\fR]
[\fB\-\-bits\fR \fIBITS\fR]
.IR file ...
.SH DESCRIPTION
.B corrupt
modifies files by toggling a randomly chosen bit.
.SH OPTIONS
.TP
.BR \-n ", " \-\-bits =\fIBITS\fR
Set the number of bits to modify.
Default is one bit." | diction
(stdin):12: SH OPTIONS .TP .BR \-n , \-\-bits =\fIBITS\fR Set the
[number of] bits to modify.

(stdin):16: Default is [one] bit.

2 phrases in 3 sentences found.


And yet, the tested text is non-sensible.

Fun fact: Lewis Carroll's Jabberwocky tests as very readable.
readability grades:
        Kincaid: 2.6
        ARI: 3.4
        Coleman-Liau: 9.1
        Flesch Index: 94.1/100
        Fog Index: 5.7
        Lix: 23.1 = below school year 5
        SMOG-Grading: 6.6

(stdin):11: Long time the manxome foe he sought -- [So] rested he by the
Tumtum tree, And stood a [while] in thought.

(stdin):20: [One] two!

(stdin):20: [One] two!

(stdin):22: He left it dead, and with [its] head He went galumphing back.

5 phrases in 16 sentences found.



I could go on, but surely I have, enough, already.



Kind regards





More information about the linux mailing list