From 3e132ef580e87d4f712b3f3823c63ba6bea0f60d Mon Sep 17 00:00:00 2001 From: Lloyd Snow Date: Sat, 6 Oct 2012 13:30:29 -0500 Subject: [PATCH 1/4] a version of basic.awk that has a simple way to be debugged when rst output is used. --- lib/basic.debug.awk | 84 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 lib/basic.debug.awk diff --git a/lib/basic.debug.awk b/lib/basic.debug.awk new file mode 100644 index 0000000..c73b1ef --- /dev/null +++ b/lib/basic.debug.awk @@ -0,0 +1,84 @@ +# This is a basic gawk backend for bashdoc(1) +# (c) 2007 Andrés J. Díaz +# -- +# This file is part of bashdoc project. + +# At the beggining set the flag last_comment to 0, this flag is used to +# detect when a code block starts (or a comment block ends). +BEGIN { last_comment=0; debug=1 } + +# We ignore lines which starts by a comment followed by exclamation mark or +# minus sign. +/^[#]!/ { + if (debug == 0) + next + else + print ""$0 +} +/^[#]-/ { + if (debug == 0) + next + else + print ""$0 +} + +# Code block parser. We consider a code block everthing which are not +# a comment block. We print the :: mark (starts a pre-formated block in RST) +# only at the beggining of code block. +/^[:space:]*[^#\n].*/ { + if (last_comment == 1) + printf "\n\n::\n\n" + last_comment=0 + if (debug == 0) + print " "$0 + else + print " "$0 +} + +# The following rules create a RST notes for each codification label, such +# as TODO, FIXME and XXX. +/^[#][ ]*TODO.*/ { + print "\n.. note:: To-Do" + sub("^[#][ ]*TODO[:]?","") + if (debug == 0) + print " "$0 + else + print " "$0 +} +/^[#][ ]*FIXME.*/ { + print "\n.. note:: Fix me" + sub("^[#][ ]*FIXME[:]?","") + if (debug == 0) + print " "$0 + else + print " "$0 +} +/^[#][ ]*XXX.*/ { + print "\n.. note:: Hack" + sub("^[#][ ]*XXX[:]?","") + if (debug == 0) + print " "$0 + else + print " "$0 +} + +# Comment block parser. A comment block is a number of lines starting by +# a sharp symbol (#). We also accept lines in advanced bsah guide format, +# such as #+ and #>. Some text are parser specially, for example the +# copyright line in emphatized, and both, copyright and registered symbols +# are substituted. +/^[#].*/ { + last_comment=1 + sub("^[:space:]*#[+> ]*","") + sub("^[Cc]opyright.*","*&*") + sub("\\([cC]\\)","©") + sub("\\([rR]\\)","®") + + if (debug == 0) + printf "\n%s",$0 + else + printf "\n%s",$0 +} + +# Finally print the EOL (we do not put the EOL when parsing comment block. +END { printf "\n" } From b21e6cedbb4c6446355e302fb894c61dcb41a360 Mon Sep 17 00:00:00 2001 From: Lloyd Snow Date: Sat, 6 Oct 2012 13:33:38 -0500 Subject: [PATCH 2/4] fixed a bug where bashdoc would fail to produce rst output. --- bashdoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/bashdoc b/bashdoc index 4be359c..c193f95 100755 --- a/bashdoc +++ b/bashdoc @@ -92,8 +92,10 @@ fi # Determine in .py extension is present in rst2* scripts. Debian and other # deb-based distributions omit the extension of the scripts. -require rst2${format} || { require rst2${format}.py && py=".py" ;} || - E=1 fatal $"rst backend not found (rst2${format})" +case $format in + none|raw|rst) ;; + *) require rst2${format} || { require rst2${format}.py && py=".py" ;} || E=1 fatal $"rst backend not found (rst2${format})" ;; +esac # Redirect output to output_file if present. if [ "${output_file}" ]; then @@ -102,9 +104,8 @@ fi # Handler for none format (aka raw, aka rst). If none format is used, then # result is in plain rst format. -case $2 in +case $format in none|raw|rst) rst_maker "$1";; *) rst_maker "$1" | rst2${format}${py} ;; esac -#- vim:foldmethod=syntax:foldenable: From 5d480e26b63ed10cd86c87c863d82c94d0ace568 Mon Sep 17 00:00:00 2001 From: Lloyd Snow Date: Sat, 6 Oct 2012 13:35:42 -0500 Subject: [PATCH 3/4] fixed an invisible bug in basic.awk --- lib/basic.awk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/basic.awk b/lib/basic.awk index db6cfc2..dd07add 100644 --- a/lib/basic.awk +++ b/lib/basic.awk @@ -15,7 +15,7 @@ BEGIN { last_comment=0; } # Code block parser. We consider a code block everthing which are not # a comment block. We print the :: mark (starts a pre-formated block in RST) # only at the beggining of code block. -/^[:space:]*[^#\n].*/ { +/^[[:space:]]*[^#\n].*/ { if (last_comment == 1) printf "\n\n::\n\n" last_comment=0 From a108200d96f133da8583eb51da3c1c6384fbf4a1 Mon Sep 17 00:00:00 2001 From: Lloyd Snow Date: Sat, 6 Oct 2012 13:37:27 -0500 Subject: [PATCH 4/4] added a handler; basically a wip rewrite of basic.awk. --- lib/better.basic.awk | 149 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 lib/better.basic.awk diff --git a/lib/better.basic.awk b/lib/better.basic.awk new file mode 100644 index 0000000..90fec4b --- /dev/null +++ b/lib/better.basic.awk @@ -0,0 +1,149 @@ +# This is an attempted at a correction to the basic gawk backend for bashdoc(1) +# the author doesn't really understand liscenses & copyright; don't be a dick. + +# initial state +BEGIN { + debug = 0 + bash_pound_comment_line = 0 + styled_bash_pound_comment_line = 0 + consecutive_noncomment_lines = 0 + ignore_this_line = 0 +} + +# Skip shebangs +(FNR == 1) && /^#!.*$/ { + if (debug == 1) + print "*next*; shebang:"$0 + next +} + +# I haven't played around with these yet; straight from the original basic.awk: +# The following rules create a RST notes for each codification label, such +# as TODO, FIXME and XXX. +# /^[#][ ]*TODO.*/ { +# print "\n.. note:: To-Do" +# sub("^[#][ ]*TODO[:]?","") +# if (debug == 0) +# print " "$0 +# else +# print " "$0 +# } +# /^[#][ ]*FIXME.*/ { +# print "\n.. note:: Fix me" +# sub("^[#][ ]*FIXME[:]?","") +# if (debug == 0) +# print " "$0 +# else +# print " "$0 +# } +# /^[#][ ]*XXX.*/ { +# print "\n.. note:: Hack" +# sub("^[#][ ]*XXX[:]?","") +# if (debug == 0) +# print " "$0 +# else +# print " "$0 +# } + +# detection first, printing later +# ------------------------------- + +# detect anything that is not a 'bash-#-comment-only line' +/^[[:space:]]*[^#].*$/ { + bash_pound_comment_line = 0 + styled_bash_pound_comment_line = 0 + ignore_this_line = 0 + if (debug == 1) + print "not a 'bash-#-comment-only line':"$0 +} +# detect anything that is a 'bash-#-comment-only line' +/^[[:space:]]*[#].*$/ { + bash_pound_comment_line = 1 + styled_bash_pound_comment_line = 0 + ignore_this_line = 0 + if (debug == 1) + print "is a 'bash-#-comment-only line':"$0 +} +# detect anything that is a styled 'bash-#-comment-only line' and which we should not ignore +/^[[:space:]]*[#][![:space:]].*$/ { + if ((debug == 1) && (bash_pound_comment_line != 1)) + print "*error state*; 'bash-#-comment-only line' should have already registered." + styled_bash_pound_comment_line = 1 + ignore_this_line = 0 + if (debug == 1) + print "is a styled 'bash-#-comment-only line':"$0 +} +# detect anything that is a styled 'bash-#-comment-only line' and which we should ignore +/^[[:space:]]*[#][^![:space:]].*$/ { + if ((debug == 1) && (bash_pound_comment_line != 1)) + print "*error state*; 'bash-#-comment-only line' should have already registered." + styled_bash_pound_comment_line = 1 + ignore_this_line = 1 + if (debug == 1) + print "*ignored*; is a styled 'bash-#-comment-only line':"$0 +} +# detect blank lines because nothing else will +/^$/ { + bash_pound_comment_line = 0 + styled_bash_pound_comment_line = 0 + ignore_this_line = 1 + if (debug == 1) + print "*ignored*; is a blank line:"$0 +} +# I can't think of a way to account for the following comments using a single regexp or just a few regexps (textbook regexs shouldn't be able to catch the patterns of these lines) +# These could be accounted for individually, but that would be bad for users (it would dash their unentitled expectations and make them rage, a lot) and would not scale to cover the more general problem. +# +# ^$((muffin--)) # I have less muffins now.$ +# +# ^wigglytuff_used='#' # It's not very effective.$ +# +# ^wigglytuff_used='##' # It's not very effective.$ +# +# ^wigglytuff_used='#"' # It's not very effective.$ +# +# ^wigglytuff_used='"#"' # It's not very effective.$ +# +# ^wigglytuff_used="#'" # It's not very effective.$ +# +# ^wigglytuff_used="# # It's not very effective.$ +# +# ^} # And *that* was the best function ever.$ +# +# ^{ # don't you want some chocolate right now?$ +# +# ^{ # } # tread carefully if you try to implement single curly-brace cases$ +# + +# printing now +# ------------ + +# If the ignore_this_line flag's state survived this far, then honor it. +ignore_this_line == 1 { + if (debug == 1) + print "*next*; *ignored*:"$0 + next +} + +# print a thing that is exactly a 'bash-#-comment-only line' +(bash_pound_comment_line == 1) && (styled_bash_pound_comment_line == 0) && (parentheses_then_bash_pound_comment_line == 0) { + sub("^[[:space:]]*#","") + printf "\n%s",$0 + consecutive_noncomment_lines = 0 +} +# print a thing that is exactly a styled 'bash-#-comment-only line' +(bash_pound_comment_line == 1) && (styled_bash_pound_comment_line == 1) && (parentheses_then_bash_pound_comment_line == 0) { + sub("^[[:space:]]*#[![:space:]]","") + printf "\n%s",$0 + consecutive_noncomment_lines = 0 +} +# anything that is not a comment, is code; For each code line, if it is consecutively the first such of its code block, then treat it specially. +(bash_pound_comment_line == 0) && (consecutive_noncomment_lines == 0) && (parentheses_then_bash_pound_comment_line == 0) { + printf "\n\n::\n\n" +} +# anything that is not a comment, is code; print it now. +bash_pound_comment_line == 0 { + print " "$0 + ++consecutive_noncomment_lines +} + +END { printf "\n" }