Documentation/make-cg-asciidoc

   1 #!/usr/bin/env bash
   2 #
   3 # Generate asciidoc manpage markup from Cogito script header.
   4 # Copyright (c) Jonas Fonseca, 2005
   5 #
   6 # Takes a path to a Cogito script. Prints the manpage to stdout.
   7
   8 PACKAGE=${CGPACKAGE:-cogito}
   9
  10 command=$1
  11
  12 if [ ! -e "$command" ]; then
  13         echo "$command does not exist" >&2
  14         exit
  15 fi
  16
  17 COMMAND=$(basename $command)
  18
  19 # FIXME: Show the SHA1 of the command below the TITLELINE.
  20
  21 # Generate the 'CG-COMMAND(1)' title from cg-command
  22 TITLE="$COMMAND(1)"
  23 # Asciidocs wants the title line ('====') to be as wide as the title.
  24 TITLELINE=$(echo "$TITLE" | sed 's/[0-9a-zA-Z()-]/=/g')
  25
  26 # Get `USAGE="cg-command args..."` line and make it `cg-command args...`
  27 SYNOPSIS=$(sed -n '/^USAGE=/,0s/^USAGE="\(.*\)"/\1/p' < $command)
  28
  29 # Extract the script header.
  30 HEADER=$(sed -n '3,/^$/s/^# *//p' < $command)
  31
  32 # Some scripts have copyright lines followed by 'Based on script by ...' lines.
  33 # Include them so they are also put in the COPYRIGHT section.
  34 COPYRIGHT=$(echo "$HEADER" | sed -n '/^Copyright (c)/,/^$/p' \
  35                            | sed 's/(c)/(C)/')
  36
  37 # First line of the header contains the caption. Normalize it by lowercasing the
  38 # start and stripping any punctuation.
  39 CAPTION=$(echo "$HEADER" | head -n 1 | tr '[A-Z]' '[a-z]' | sed 's/\.$//')
  40
  41 # Get remaining sections and carefully insert links to cogito commands when they
  42 # were referenced as "`cg-command`". This way references from cg-* combos in
  43 # code listings will be ignored.
  44 BODY=$(echo "$HEADER" | sed '0,/^$/d' \
  45                       | sed 's/`\(cg-[a-z-]\+\)`/gitlink:\1[1]/g;s/^\(-.*\)::.*/\1::/')
  46
  47 DESCRIPTION=
  48 OPTIONS=
  49 MISC=
  50
  51 section=$(echo "$BODY" | sed -n '1,/^[-][-]*[-]$/p')
  52 section_lines=$(echo "$section" | wc -l)
  53 lines=$(echo "$BODY" | wc -l)
  54
  55 if [ $section_lines = $lines ]; then
  56         DESCRIPTION="$BODY"
  57
  58 else
  59         section_end=$(($section_lines - 2))
  60         DESCRIPTION=$(echo "$BODY" | sed -n "1,${section_end}p")
  61         BODY=$(echo "$BODY" | sed -n "$((section_lines - 1)),\$p")
  62
  63         if [ "$(echo "$BODY" | head -n 1)" = "OPTIONS" ]; then
  64                 BODY=$(echo "$BODY" | sed -n '3,$p')
  65                 section=$(echo "$BODY" | sed -n "1,/^[-~][-~]*[-~]\$/p")
  66                 section_lines=$(echo "$section" | wc -l)
  67                 lines=$(echo "$BODY" | wc -l)
  68
  69                 if [ $section_lines = $lines ]; then
  70                         OPTIONS="$BODY"
  71                 else
  72                         section_end=$(($section_lines - 2))
  73                         OPTIONS=$(echo "$BODY" | sed -n "1,${section_end}p")
  74                         MISC=$(echo "$BODY" | sed -n "${section_end},\$p")
  75                 fi
  76
  77         else
  78                 MISC="$BODY"
  79         fi
  80 fi
  81
  82 # cg(1) does not answer to the help options in the same way as the
  83 # rest of the commands
  84 if [ "$COMMAND" = "cg" ]; then
  85         HELP_OPTIONS="
  86 -h, --help::
  87         Print overview of Cogito commands. Same as gitlink:cg-help[1]."
  88 else
  89         HELP_OPTIONS="
  90 -h, --help::
  91         Print usage summary.
  92
  93 --long-help::
  94         Print user manual. The same as found in gitlink:$COMMAND[1]."
  95 fi
  96
  97 cat <<__END__
  98 $TITLE
  99 $TITLELINE
 100
 101 NAME
 102 ----
 103 $COMMAND - $CAPTION
 104
 105 SYNOPSIS
 106 --------
 107 $SYNOPSIS
 108
 109 DESCRIPTION
 110 -----------
 111 $DESCRIPTION
 112
 113 OPTIONS
 114 -------
 115
 116 --
 117 __END__
 118
 119 # Only indent the first paragraph of multi-paragraph list items.
 120 multipara=
 121 echo "$OPTIONS" | while read line; do
 122         case "$line" in
 123         *::)
 124                 multipara=
 125                 ;;
 126         "")
 127                 multipara=t
 128                 ;;
 129         *)
 130                 [ "$multipara" ] || line="      $line"
 131         esac
 132
 133         echo "$line"
 134 done
 135
 136 cat <<__END__
 137
 138 $HELP_OPTIONS
 139
 140 --version::
 141         Print Cogito version.
 142 --
 143
 144 $MISC
 145
 146 COPYRIGHT
 147 ---------
 148 $COPYRIGHT
 149
 150 SEE ALSO
 151 --------
 152 $COMMAND is part of gitlink:${PACKAGE}[7],
 153 a toolkit for managing gitlink:git[7] trees.
 154 __END__