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

 
 

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

Submitted by:  Reuben Thomas <rrt>
Submitted on:  Mon 26 Sep 2011 08:48:24 PM UTC  
 
Category: NoneSeverity: 3 - Normal
Item Group: NoneStatus: None
Privacy: PublicAssigned to: None
Originator Name: Open/Closed: Open

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

Please log in, so followups can be emailed to you.

 

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>
Project 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 File(s):
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by bettini (Posted a comment)
  • -unavailable- added by rrt (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item

    Back to the top


    Powered by Savane 3.1-cleanup