bugGNU Gengetopt - Bugs: bug #34396, Please don't document gnulib in...

 
 

bug #34396: Please don't document gnulib in the gengetopt manual

Submitter:  Reuben Thomas <rrt>
Submitted:  Mon 26 Sep 2011 08:48:24 PM UTC
   
 
Category:  None Severity:  3 - Normal
Item Group:  None Status:  None
Privacy:  Public Assigned to:  None
Originator Name:  Open/Closed:  Open
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 30 Sep 2011 12:55:17 AM UTC, comment #3: 

Actually, I retract my previous comment.

getopt_long is a standard POSIX API. So, most systems implement it. (I assume that gengetopt only uses it per the POSIX spec; if not, that should be fixed, although it would be reasonable for gengetopt to detect GNU getopt and use that where available.)

Hence, it's reasonable to give a tip: "if you're using gnulib, use its getopt module for better support on systems with missing or buggy getopt", but that's all the documentation you need for section 12.

Reuben Thomas <rrt>
Wed 28 Sep 2011 02:07:14 PM UTC, comment #2: 

Repeating another program's documentation is exactly the sort of problem I'm talking about: it creates an unnecessary maintenance burden.

Having re-read the other section about including getopt_long, I agree that it is best left there.

Reuben Thomas <rrt>
Wed 28 Sep 2011 08:50:16 AM UTC, comment #1: 

Actually I repeated a part of gnulib documentation so that the user can simply follow those instructions and setup his autotools quickly without having to read all the gnulib documentation; I'd be tempted to leave that part in gengetopt's documentation

As for the old method I'd be tempted to leave that as well, since gengetopt's users might not use autotools at all...

Lorenzo Bettini <bettini>
Group administrator
Mon 26 Sep 2011 08:48:24 PM UTC, original submission:  

I am delighted to see that you use gnulib in gengetopt. However, I don't think it's a good idea to put detailed documentation on how to use gnulib in the gengetopt manual. The place for that is the gnulib manual. This is for two reasons: first, your  documentation duplicates the gnulib manual; and secondly, it risks getting out of date.

I suggest that you proceed as follows: in the section "Use automake/autoconf to check for the existence of `getopt_long'", remove the two sub-pages (there is no need to keep the old method "Use getopt_long sources"). Then, remove the main paragraph, and replace it with something like this:

If your program's build system uses the GNU autotools, the easiest way to ensure that you have `getopt_long' is to use gnulib's `getopt' module. See the gnulib manual, or http://www.gnu.org/s/gnulib/ for more information.

(By the way, I believe that the getopt-posix module should also work; if that's true you can change "`getopt'" to "`getopt' or
`getopt-posix'" above.)

If you think you have explained something better than the gnulib manual, then by all means submit a patch; I know the gnulib authors are always happy to receive patches to gnulib and its documentation.

Reuben Thomas <rrt>

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by bettini (Posted a comment)
  • -email is unavailable- added by rrt (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.

    Only logged-in users can vote.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code