bugGNU nano - Bugs: bug #64125, command syntax in synopsis is...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

bug #64125: command syntax in synopsis is incorrect

Submitter:  Eric S. Raymond <esr>
Submitted:  Sat 29 Apr 2023 02:00:24 PM UTC
   
 
Severity:  2 - Minor Status:  Fixed
Assigned to:  bens Open/Closed:  Open

Mon 01 May 2023 08:58:41 AM UTC, comment #3: 

Thanks for explaining.  Fixed in git, commit 2c19345e:
https://git.savannah.gnu.org/cgit/nano.git/commit/?id=2c19345e

(Doclifter...  In your original submission you mistyped it as "docliter".  I wondered what it was and tried to google it.  Half of the occurrences were OCR mistakes for "dochter" -- Dutch for "daughter".)

Submitting a patch for man-pages(7) would be good.

Benno Schulenberg <bens>
Group administrator
Mon 01 May 2023 12:02:10 AM UTC, comment #2: 

Awkwardly, there is no single written authoritative source for how command synopses should be written. You have to learn it by looking at lots of examples, and sometimes tripping over what the few tools that parse these synopses do.

I have had to read literally tthousands of command synopses because I maintain doclifter, a tool that analyzes man pages and lifts them to structural DocBook-XML.  Running doclifter against the entire manual tree of a Linux distribution is educational.  The parser has to reject anything that can't be rendered in DocBook markup, so I spend a lot of time plowing through synopsis that (for example) accidentally leave off a trailing ] in an optional part. That is probably the single most common error.

Usage is surprisingly consistent.  Every couple of years I do a cleanuo run where I do that trial conversion of an entire manual tree, then send fix patches to ebevery maintainer of a page with bad markup I can locate.  This year I have run doclifter against 11335 manual pages and found only 413 that need fixes, most of those being due to obvious typos rather than failure to follow standard usage,

Mayne I should document correct usage.  That's a thought.


Eric S. Raymond <esr>
Sun 30 Apr 2023 06:19:50 AM UTC, comment #1: 

Okay.  But where is this use of braces documented?  In `man 7 man-pages` only brackets, vertical bars, and ellipses are mentioned.

Benno Schulenberg <bens>
Group administrator
Sat 29 Apr 2023 02:00:24 PM UTC, original submission:  

The nano command syntax uses parens ( ) for a mandatory part of an option. This is incorrect and confuses docliter's attempts to lift the page to clean Docbook-XML.  Squiggly brackets { } should be used instead.

Please apply the attached patch.

Eric S. Raymond <esr>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attached Files
file #54686:  pico.1.patch added by esr (450B - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by bens (Posted a comment)
  • -email is unavailable- added by esr (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2023-05-01 bens StatusNeed Info Fixed
    2023-04-30 bens Severity3 - Normal 2 - Minor
        StatusNone Need Info
        Assigned toNone bens
        Summarycommand syntax is icorrect command syntax in synopsis is incorrect
    2023-04-29 esr Attached File- Added pico.1.patch, #54686

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code