Missing man page for getopt_long(3C)

Review Request #1137 — Created July 18, 2018 and submitted

jbk
illumos-gate
9659
general

Missing man page for getopt_long(3C). Based off the NetBSD getopt_long(3) man page.



  • 1
  • 0
  • 19
  • 0
  • 20
Description From Last Updated
Does getopt_long have the same issue that is described in the USAGE section of getopt(3C)? rm rm
yuripv
  1. 
      
  2. usr/src/man/man3c/Makefile (Diff revision 1)
     
     

    I think we sort on the last column here.

    1. Yeah -- at least mostly (e.g. I think 'get_nprocs_conf.3c' is probably in the wrong spot). But I'll at least not make it worse.

  3. usr/src/man/man3c/getopt_long.3c (Diff revision 1)
     
     

    Is there any point in keeping this?

  4. usr/src/man/man3c/getopt_long.3c (Diff revision 1)
     
     

    Looks useless, not part of copyright/license anyway.

  5. usr/src/man/man3c/getopt_long.3c (Diff revision 1)
     
     

    Just remove.

  6. usr/src/man/man3c/getopt_long.3c (Diff revision 1)
     
     

    We don't seem to provide the library when it's libc in other man pages, thought it could be that those others should be fixed instead.

  7. This doesn't seem to be sorted correctly, did you run pkgfmt from within the buildenv?

  8. 
      
yuripv
  1. Just some integrations nits, which don't have to be addressed.

  2. 
      
jbk
rm
  1. 
      
  2. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    This manual page is missing a few sections:
    
    INTERFACE STABILITY
    MT SAFETY
    1. What would be the interface stability? Uncommitted?

    2. It's committed.

  3. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    For what it's worth, we've been trying to standardize on one arg per line.
    1. Ok -- that's just how it was from NetBSD, but no reason we can't adjust it.

  4. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    This is missing a section on ERRORS given that we're describing errno being set.
  5. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    Presumably the environment variables that are mentioned in getopt(3C) all apply here, no?
    1. Looking at the implementations of both getopt(3C) and getopt_long(3C) (I'm assuming both are the ones in the respective files under usr/src/lib/libc/port/gen) I think actually just LANG and LC_MESSAGES are the only relevant ones for both -- I cannot see anything obvious that would be impacted by LC_CTYPE (it looks like both implementations iterate optstring by byte, and any comparisons are to hardcoded values).

  6. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    glibc-2.1.3 is pretty old. Is this still true today?
    1. I don't know how well NetBSD has kept up here, and linux man pages aren't very instructive. I wonder if it would just be better to maybe replace this section with something similar to 'While the illumos implementations of getopt_long and getopt_long_only are broadly compatible with other implementations, the following edge-cases have been known to historically vary among implementations:' + explain the edge case and just document the illumos behavior. That way we don't have to worry about trying to keep up with what either the BSDs or GLIBC is doing (or worry about tracking versions, etc.). Thoughts?

    2. I think that's probably a better way to phrase it. Especially since it talks about the impl in NetBSD, but then everything refers to BSD generically.

  7. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
     
     

    This sentence doesn't really make sense. Reading it initially it's not clear what applies to illumos. I get that the source for this originally came from netbsd, but we should just describe it as our implementation. Also it's comparing three different implementations.

    1. Would 'This section describes the differences in implementation found in glibc-2.1.3, the BSD implementation found in NetBSD, and the implementation found in illumos' be better? Our implementation has a bit of a mix between the BSD and GNU behavior (for example, an old Sun case changed the behavior of the 'W;' value in optstring (in the face of an unknown option) from the BSD behavior to the GNU behavior, so I don't think we probably want to compare to both BSD and GNU.

    2. I actually think that the string you suggested in the previous sentence was better. Specifically 'While the illumos implementations of getopt_long and getopt_long_only are broadly compatible with other implementations, the following edge-cases have been known to historically vary among implementations:'

  8. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    Why is this section commented out? Is it invalid, not true, or something else? If it's just not valid, we should probably just delete it.
    1. That's how it was on NetBSD -- I'm not entirely sure why they have it commented out (perhaps old information -- a lot of them are dealing with GNU compatability issues, which is probably a bit of a moving target). I'll remove these, and worst case we can always go back to the NetBSD source to get them if they need to be revived.

  9. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     

    Why is this section commented out?

    1. Probably the same as above.

  10. usr/src/man/man3c/getopt_long.3c (Diff revision 2)
     
     
    Does getopt_long have the same issue that is described in the USAGE section of getopt(3C)?
  11. 
      
jbk
rm
  1. 
      
  2. usr/src/man/man3c/getopt_long.3c (Diff revisions 2 - 3)
     
     
     
     
     
     
     
     
    This information should be in the RETURN VALUES section. If you look at other manual pages, conventionally we'll say something like:
    
    .Sh ERRORS
    The
    .Fn function name
    function will fail if:
    .Bl -tag -width Er
    .El
  3. usr/src/man/man3c/getopt_long.3c (Diff revisions 2 - 3)
     
     
     
     
     
     
     
     
     
    I think your other sentence was better:
    
    While the illumos implementations of getopt_long and getopt_long_only are broadly compatible with other implementations, the following edge-cases have been known to historically vary among implementations:
  4. usr/src/man/man3c/getopt_long.3c (Diff revisions 2 - 3)
     
     
     
    I missed this on the first pass, but looking at the way this list is constructed, I understand why things are being down with two rows; however, semantically that isn't correct and this will be much more obvious in non-plain text rendering (like HTML).
    
    As effectively it's going to turn into three different entries, one for GNU, one empty line for BSD, and then one for illumos. I'd suggest instead doing it where when we have two OSes that are doing the same thing, we combine them into the same .It header.
  5. usr/src/man/man3c/getopt_long.3c (Diff revisions 2 - 3)
     
     
    This should actually be:
    
    .Sh MT-LEVEL
  6. 
      
jbk
jbk
rm
  1. Thanks for the clean up. I only found one additional thing which wasn't clear.

    1. Hrm yeah -- I think the original BSD manpage just assumes you go look at getopt(3C) to figure out that. However I'll add some lines explicitly explaining their use here.

  2. usr/src/man/man3c/getopt_long.3c (Diff revision 5)
     
     
     
     
    Looking through this again, I didn't find any discussion of what these variables are. When they are set, and what they signify.
    1. I've updated with references to optopt and opterr, but not optreset -- we use that internally, but unlike the BSD implementation, do not currently export that, so no point in mentioning it at all.

  3. 
      
jbk
rm
  1. Thanks for the update. This generally looks good. Please audit your use of .Va. It's only supposed to be used for variables. There are a lot of cases where you're using it incorrectly for structure and function arguments which should be .Fa. Otherwise, this looks good.

  2. usr/src/man/man3c/getopt_long.3c (Diff revisions 5 - 6)
     
     
    Structure members are supposed to use .Fa per mdoc(5).
  3. usr/src/man/man3c/getopt_long.3c (Diff revisions 5 - 6)
     
     
    optstring is a function argument. It should use .Fa, not .Va. Here and elsewhere.
  4. 
      
jbk
rm
  1. Thanks for the clean up there.

  2. 
      
yuripv
  1. Ship It!
  2. 
      
jbk
Review request changed

Status: Closed (submitted)

Loading...