From 0e3549bef3a421e3eb02b56419db1d8eb7985591 Mon Sep 17 00:00:00 2001 From: "Barak A. Pearlmutter" Date: Wed, 4 Apr 2018 11:55:52 +0100 Subject: [PATCH 1/5] txt2man options Pass appropriate options to txt2man to get a proper .TH line. These are -s 1 for the section, we skip -d xxx for the date, which will default to the debian/changelog timestamp during a debian package build, or otherwise to the current date. Then -r origin-aka-project-name-and-version -v volume-aka-section-name. Gbp-Pq: Name 0003-txt2man-options.patch --- CMake/exec2man.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CMake/exec2man.sh b/CMake/exec2man.sh index b0807fc614..8cf34e92b0 100755 --- a/CMake/exec2man.sh +++ b/CMake/exec2man.sh @@ -75,6 +75,6 @@ synopsis="$name [-h] [-v] $reqoptions $options"; sed 's/ / /g' | \ awk '/NAME/,/REQUIRED OPTIONS/ { print; } /ADDITIONAL INFORMATION/,0 { print; } /REQUIRED OPTIONS/,/ADDITIONAL INFORMATION/ { if (!/REQUIRED_OPTIONS/ && !/OPTIONS/ && !/ADDITIONAL INFORMATION/) { if (/ --/) { printf "\n" } sub(/^[ ]*/, ""); sub(/ [ ]*/, " "); printf "%s ", $0; } else { if (!/REQUIRED OPTIONS/ && !/ADDITIONAL INFORMATION/) { print "\n"$0; } } }' | \ sed 's/ ADDITIONAL INFORMATION/\n\nADDITIONAL INFORMATION/' | \ - txt2man -P mlpack -t "$name" -d 1 | \ + txt2man -t "$name" -s 1 -r "MLPACK Utilities" -v "User Commands" | \ sed "s/^'/\\\\(aq/" > "$output" From 7895f7d8e33c22d83de217d2f4879167593ea4de Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Thu, 5 Apr 2018 09:43:46 +0100 Subject: [PATCH 2/5] update exec2man.sh updates to handle newer mlpack_xxx --help text see https://gist.github.com/rcurtin/c1cb5ef47abed9e9a8a21f5d9701eb0f Gbp-Pq: Name 0004-update-exec2man.sh.patch --- CMake/exec2man.sh | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CMake/exec2man.sh b/CMake/exec2man.sh index 8cf34e92b0..e49a110303 100755 --- a/CMake/exec2man.sh +++ b/CMake/exec2man.sh @@ -1,5 +1,5 @@ #!/bin/bash -# Convert the output of an MLPACK executable into a man page. This assumes that +# Convert the output of an mlpack executable into a man page. This assumes that # the CLI subsystem is used to output help, that the executable is properly # documented, and that the program is run in the directory that the executable # is in. Usually, this is used by CMake on Linux/UNIX systems to generate the @@ -17,7 +17,7 @@ output="$2" # Generate the synopsis. # First, required options. reqoptions=`./"$name" -h | \ - awk '/Required options:/,/Options:/' | \ + awk '/Required input options:/,/Optional input options:/' | \ grep '^ --' | \ sed 's/^ --/--/' | \ sed 's/^--[A-Za-z0-9_-]* (\(-[A-Za-z0-9]\))/\1/' | \ @@ -31,7 +31,7 @@ reqoptions=`./"$name" -h | \ # Then, regular options. options=`./"$name" -h | \ - awk '/Options:/,/For further information,/' | \ + awk '/Optional input options:/,/For further information,/' | \ grep '^ --' | \ sed 's/^ --/--/' | \ grep -v -- '--help' | \ @@ -50,7 +50,7 @@ options=`./"$name" -h | \ sed 's/\(-[A-Za-z0-9] [a-z]*\) /\[\1\] /g' | \ sed 's/\(--[A-Za-z0-9_-]* [a-z]*\) /\[\1\] /g'` -synopsis="$name [-h] [-v] $reqoptions $options"; +synopsis="$name $reqoptions $options [-h -v]"; # Preview the whole thing first. #./$name -h | \ @@ -68,12 +68,12 @@ synopsis="$name [-h] [-v] $reqoptions $options"; ./"$name" -h | \ sed 's/^For further information/Additional Information\n\n For further information/' | \ sed 's/^consult the documentation/ consult the documentation/' | \ - sed 's/^distribution of MLPACK./ distribution of MLPACK./' | \ + sed 's/^distribution of mlpack./ distribution of mlpack./' | \ awk -v syn="$synopsis" \ '{ if (NR == 1) print "NAME\n '"$name"' - "tolower($0)"\nSYNOPSIS\n "syn" \nDESCRIPTION\n" ; else print } ' | \ sed '/^[^ ]/ y/qwertyuiopasdfghjklzxcvbnm:/QWERTYUIOPASDFGHJKLZXCVBNM /' | \ sed 's/ / /g' | \ - awk '/NAME/,/REQUIRED OPTIONS/ { print; } /ADDITIONAL INFORMATION/,0 { print; } /REQUIRED OPTIONS/,/ADDITIONAL INFORMATION/ { if (!/REQUIRED_OPTIONS/ && !/OPTIONS/ && !/ADDITIONAL INFORMATION/) { if (/ --/) { printf "\n" } sub(/^[ ]*/, ""); sub(/ [ ]*/, " "); printf "%s ", $0; } else { if (!/REQUIRED OPTIONS/ && !/ADDITIONAL INFORMATION/) { print "\n"$0; } } }' | \ + awk '/NAME/,/.*OPTIONS/ { if (!/.*OPTIONS/) { print; } } /ADDITIONAL INFORMATION/,0 { print; } /.*OPTIONS/,/ADDITIONAL INFORMATION/ { if (!/REQUIRED INPUT OPTIONS/ && !/OPTIONAL INPUT OPTIONS/ && !/OPTIONAL OUTPUT OPTIONS/ && !/ADDITIONAL INFORMATION/) { if (/ --/) { printf "\n" } sub(/^[ ]*/, ""); sub(/ [ ]*/, " "); printf "%s ", $0; } else { if (!/ADDITIONAL INFORMATION/) { print "\n"$0; } } }' | \ sed 's/ ADDITIONAL INFORMATION/\n\nADDITIONAL INFORMATION/' | \ txt2man -t "$name" -s 1 -r "MLPACK Utilities" -v "User Commands" | \ sed "s/^'/\\\\(aq/" > "$output" From daa670db039867efeddfcbdd563ab36ed603d1e5 Mon Sep 17 00:00:00 2001 From: "Barak A. Pearlmutter" Date: Wed, 4 Apr 2018 13:44:15 +0100 Subject: [PATCH 3/5] spelling Gbp-Pq: Name 0005-spelling.patch --- src/mlpack/methods/rann/ra_model_impl.hpp | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/mlpack/methods/rann/ra_model_impl.hpp b/src/mlpack/methods/rann/ra_model_impl.hpp index 093ce74d10..7e4753603c 100644 --- a/src/mlpack/methods/rann/ra_model_impl.hpp +++ b/src/mlpack/methods/rann/ra_model_impl.hpp @@ -222,7 +222,7 @@ bool& SingleModeVisitor::operator()(RAType* ra) const { if (ra) return ra->SingleMode(); - throw std::runtime_error("no rank-approximate model is intialized"); + throw std::runtime_error("no rank-approximate model is initialized"); } //! Exposes the referenceSet of the given RAType. @@ -231,7 +231,7 @@ const arma::mat& ReferenceSetVisitor::operator()(RAType* ra) const { if (ra) return ra->ReferenceSet(); - throw std::runtime_error("no rank-approximate model is intialized"); + throw std::runtime_error("no rank-approximate model is initialized"); } //! Exposes the Naive() method of the given RAType instance. @@ -240,7 +240,7 @@ bool& NaiveVisitor::operator()(RAType* ra) const { if (ra) return ra->Naive(); - throw std::runtime_error("no rank-approximate search model is intialized"); + throw std::runtime_error("no rank-approximate search model is initialized"); } //! For cleaning memory From 87e50cd98209a1bcca6cbf8bdab257457d041d5b Mon Sep 17 00:00:00 2001 From: Ryan Curtin Date: Fri, 6 Apr 2018 14:08:07 +0100 Subject: [PATCH 4/5] include version in origin of generated man pages --- CMake/exec2man.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/CMake/exec2man.sh b/CMake/exec2man.sh index e49a110303..f653fd4a57 100755 --- a/CMake/exec2man.sh +++ b/CMake/exec2man.sh @@ -14,6 +14,9 @@ name="$1" output="$2" +# Get the version. +version=`./"$name" --version | sed 's/^.* \([^ ]*\)\.$/\1/'` + # Generate the synopsis. # First, required options. reqoptions=`./"$name" -h | \ @@ -75,6 +78,6 @@ synopsis="$name $reqoptions $options [-h -v]"; sed 's/ / /g' | \ awk '/NAME/,/.*OPTIONS/ { if (!/.*OPTIONS/) { print; } } /ADDITIONAL INFORMATION/,0 { print; } /.*OPTIONS/,/ADDITIONAL INFORMATION/ { if (!/REQUIRED INPUT OPTIONS/ && !/OPTIONAL INPUT OPTIONS/ && !/OPTIONAL OUTPUT OPTIONS/ && !/ADDITIONAL INFORMATION/) { if (/ --/) { printf "\n" } sub(/^[ ]*/, ""); sub(/ [ ]*/, " "); printf "%s ", $0; } else { if (!/ADDITIONAL INFORMATION/) { print "\n"$0; } } }' | \ sed 's/ ADDITIONAL INFORMATION/\n\nADDITIONAL INFORMATION/' | \ - txt2man -t "$name" -s 1 -r "MLPACK Utilities" -v "User Commands" | \ + txt2man -t "$name" -s 1 -r "mlpack-$version" -v "User Commands" | \ sed "s/^'/\\\\(aq/" > "$output" From 8af6c2e7cf9ffdb13e39bafe6a2f9d2056abe13e Mon Sep 17 00:00:00 2001 From: "Barak A. Pearlmutter" Date: Fri, 6 Apr 2018 14:41:53 +0100 Subject: [PATCH 5/5] Tweak manpage-generation scripts {,all}exec2man.sh Allow executable being documented by exec2man.sh to be specified with a relative path. Output cogent usage instructions when invoked incorrectly. Use politically correct $(...) as `...` has been deprecated by glorious POSIX. Allow allexec2man.sh to use relative paths to exec2man.sh --- CMake/allexec2man.sh | 31 ++++++++++++++++++------------- CMake/exec2man.sh | 36 ++++++++++++++++++++++++++++-------- 2 files changed, 46 insertions(+), 21 deletions(-) diff --git a/CMake/allexec2man.sh b/CMake/allexec2man.sh index b8a68a18ef..1d4722f750 100755 --- a/CMake/allexec2man.sh +++ b/CMake/allexec2man.sh @@ -1,22 +1,27 @@ #!/bin/bash -# -# Convert all of the executables in this directory that are not tests to man -# pages in the given directory. -# -# Usage: -# allexec2man.sh /full/path/of/exec2man.sh output_directory/ -# -# For the executable 'cheese', the file 'cheese.1.gz' will be created in the -# output directory. + +set -e + +if [ $# != 2 ]; then + echo "Convert all of the executables in this directory that are not tests to man" + echo "pages in the given directory." + echo + echo "Usage:" + echo " allexec2man.sh /full/path/of/exec2man.sh output_directory/" + echo + echo "For the executable 'cheese', the file 'cheese.1.gz' will be created in the" + echo "output directory." + exit 1 +fi + exec2man="$1" outdir="$2" mkdir -p "$outdir" -for program in `find . -perm /u=x,g=x,o=x -iname 'mlpack_*' | \ +for program in $(find . -type f -executable -iname 'mlpack_*' | \ grep -v '[.]$' | \ - grep -v '_test$' | \ - sed 's|^./||'`; do + grep -v '_test$'); do echo "Generating man page for $program..."; - "$1" "$program" "$outdir/$program.1" + "$exec2man" "$program" "$outdir/$program.1" gzip -f "$outdir/$program.1" done diff --git a/CMake/exec2man.sh b/CMake/exec2man.sh index f653fd4a57..30268e5300 100755 --- a/CMake/exec2man.sh +++ b/CMake/exec2man.sh @@ -11,15 +11,35 @@ # No warranties... # # @author Ryan Curtin -name="$1" + +set -e + +if [ $# != 2 ]; then + echo "Generates man page from the help text of an mlpack utility program." + echo "Usage: $0 mlpack_executable generated-man-page.1" + exit 1 +fi + +exec="$1" +name="$(basename "$exec")" output="$2" +if [ "$name" = "$exec" ]; then + # if no directory prefix with explict ./ to avoid path search + exec="./$exec" +fi + +if [ ! -x "$exec" ]; then + echo "error: cannot find executable file $exec" + exit 1 +fi + # Get the version. -version=`./"$name" --version | sed 's/^.* \([^ ]*\)\.$/\1/'` +version=$("$exec" --version | sed 's/^.* \([^ ]*\)\.$/\1/') # Generate the synopsis. # First, required options. -reqoptions=`./"$name" -h | \ +reqoptions="$("$exec" --help | \ awk '/Required input options:/,/Optional input options:/' | \ grep '^ --' | \ sed 's/^ --/--/' | \ @@ -30,10 +50,10 @@ reqoptions=`./"$name" -h | \ sed 's/\(^--[A-Za-z0-9_-]* \[[A-Za-z0-9]*\]\) [^[].*/\1/' | \ tr '\n' ' ' | \ sed 's/\[//g' | \ - sed 's/\]//g'` + sed 's/\]//g')" # Then, regular options. -options=`./"$name" -h | \ +options="$("$exec" -h | \ awk '/Optional input options:/,/For further information,/' | \ grep '^ --' | \ sed 's/^ --/--/' | \ @@ -51,12 +71,12 @@ options=`./"$name" -h | \ sed 's/\(-[A-Za-z0-9]\)\( [^a-z]\)/\[\1\]\2/g' | \ sed 's/\(--[A-Za-z0-9_-]*\)\( [^a-z]\)/\[\1\]\2/g' | \ sed 's/\(-[A-Za-z0-9] [a-z]*\) /\[\1\] /g' | \ - sed 's/\(--[A-Za-z0-9_-]* [a-z]*\) /\[\1\] /g'` + sed 's/\(--[A-Za-z0-9_-]* [a-z]*\) /\[\1\] /g')" synopsis="$name $reqoptions $options [-h -v]"; # Preview the whole thing first. -#./$name -h | \ +#"$exec" -h | \ # awk -v syn="$synopsis" \ # '{ if (NR == 1) print "NAME\n '$name' - "tolower($0)"\nSYNOPSIS\n "syn" \nDESCRIPTION\n" ; else print } ' | \ # sed '/^[^ ]/ y/qwertyuiopasdfghjklzxcvbnm:/QWERTYUIOPASDFGHJKLZXCVBNM /' | \ @@ -68,7 +88,7 @@ synopsis="$name $reqoptions $options [-h -v]"; # helps avoid 'man' warnings). # The sed line at the end removes accidental macros from the output, replacing # single-quotes at the beginning of a line with the troff escape code \(aq. -./"$name" -h | \ +"$exec" -h | \ sed 's/^For further information/Additional Information\n\n For further information/' | \ sed 's/^consult the documentation/ consult the documentation/' | \ sed 's/^distribution of mlpack./ distribution of mlpack./' | \