141026.1.1 · 09397f5ba7d2007ef605a47eeab24a2ec68a9367
Revise man page (and its generation)
- Add documentation for the `--[no]group` and `-v --invert-match`
options.
- Rephrase the descriptions of some options to better distinguish
between those that actually operate ON filenames (e.g. -g, -G),
and those that output filenames, but scrutinize their contents
(e.g. -l, -L).
- Hyphenate "case-[in]sensitively".
- Insert line breaks between each option in the "OPTIONS" section.
This leads to output, particularly indentation, more consistent with
"regular" man pages, while at the same time requiring less
preprocessing work.
- Revise generate_man.sh to deal with the only formatting issue
still remaining: null characters in Markdown need an extra layer of
escaping for ronn to handle them correctly.
reading declarations
Changes to doc/generate_man.sh. All files
@@ -2,49 +2,10 @@ # ronn is used to turn the markdown into a manpage. # Get ronn at https://github.com/rtomayko/ronn+# Alternately, since ronn is a Ruby gem, you can just+# `gem install ronn` -awk '-BEGIN{- in_options_block = 0;- first_item_in_list_of_options = 1;-}--{- if ($0 == "## OPTIONS") {- in_options_block = 1;- }-- if (in_options_block == 1) { # in options block- first_4_chars = substr($0, 0, 4);-- if (first_4_chars == " * ") { # this line contains the option name-- # print only 1 new line for cases like the following- # * `--[no]group`- # * `-g PATTERN`:- if (first_item_in_list_of_options == 1) {- print "";- first_item_in_list_of_options = 0;- }-- # end the line with 2 spaces, so a literal <br> is inserted!- # more info at http://daringfireball.net/projects/markdown/syntax.php#p- printf("%s \n", substr($0, 5));-- } else if (first_4_chars == " ") { # we are in a description line- printf(" %s\n", substr($0, 5));- first_item_in_list_of_options = 1;- } else if (first_4_chars == "## F") { # reached the end of #OPTIONS part- in_options_block = 0;- print $0;- } else {- print $0;- }- } else { # outside options block- print $0;- }-}' <ag.1.md >ag.1.md.tmp-+sed -e 's/\\0/\\\\0/' <ag.1.md >ag.1.md.tmp ronn -r ag.1.md.tmp rm -f ag.1.md.tmp