class CTioga2::Commands::Documentation::Man
Converts help texts found in the Command
descriptions into a manual page that can be further edited and updated using this module.
Constants
- ItemizeIndent
- ItemizeLabel
- ItemizeLabelSize
- ManIndent
- ManualPageHeader
- RoffCommentRE
Attributes
The Doc
object Help2Man should be working on.
Public Class Methods
# File lib/ctioga2/commands/doc/man.rb, line 35 def initialize(doc) @doc = doc end
Public Instance Methods
Writes a manual page to the given io stream, using version as the target version (the one ending up in the headers).
NO… We should input a manual page, and spit out replacement texts.
# File lib/ctioga2/commands/doc/man.rb, line 47 def write_manual_page(version, input, out = STDOUT) passed_header = false if input.is_a? String filename = input input = Utils::open(input) elsif input.respond_to? :path filename = input.path else filename = "unkown" end @cmds, @groups = @doc.documented_commands @cmd_exclude = {} @group_exclude = {} while line = input.gets case line when /^#{RoffCommentRE}\s*write-header\s*$/ out.puts header_string(version, filename) passed_header = true when /^#{RoffCommentRE}\s*write-commands\s*$/ write_commands(out) # \todo add a write-backends command.... when /^#{RoffCommentRE}\s*write-group:\s*(.*)\s*$/ id = $1 if @groups[id] write_group(out, g) else warn { "Unkown group: #{id}" } end when /^#{RoffCommentRE}\s*write-types\s*$/ write_types(out) else if passed_header out.puts line end end end out.close input.close end
Protected Instance Methods
Returns the header string
# File lib/ctioga2/commands/doc/man.rb, line 249 def header_string(version, file) return ManualPageHeader % [ file, CTioga2::Version::last_modified_date, version ] end
Takes up an array of MarkupItem objects and returns its equivalent in roff format. Alternativelely, it can take a String
and feed it to MarkedUpText
.
todo make sure things are escaped the way they should be.
if inside_cmds is true, additional indentation is added for the lists, so that is looks neat in the end.
todo try to be more clever about spaces in the target file. (does not matter too much for the output of man)
# File lib/ctioga2/commands/doc/man.rb, line 107 def markup_to_man(items, inside_cmds = true) if items.is_a? String mup = MarkedUpText.new(@doc, items) return markup_to_man(mup.elements, inside_cmds) end str = "" for it in items case it when MarkedUpText::MarkupText str << it.to_s when MarkedUpText::MarkupLink str << "\\fI#{it.to_s}\\fR" when MarkedUpText::MarkupItemize indent = ItemizeIndent if inside_cmds indent += ManIndent end str << "\n.RS #{indent}" str << "\n.IP \"#{ItemizeLabel}\" #{ItemizeLabelSize}\n" str << it.items.map { |x| markup_to_man(x) }.join("\n.IP \"#{ItemizeLabel}\" #{ItemizeLabelSize}\n") str << "\n.RE\n\n" # We restore the indentation afterwards. if inside_cmds str << ".IP \"\" #{ManIndent}\n" end when MarkedUpText::MarkupVerbatim str << it.text.gsub(/^/, ' ') when MarkedUpText::MarkupParagraph str << "#{markup_to_man(it.elements)}\n\n" else raise "Markup #{it.class} isn't implemented yet for man" end end return str end
# File lib/ctioga2/commands/doc/man.rb, line 188 def write_command(out, cmd) write_command_signature(out, cmd) write_command_description(out, cmd) out.puts ".br" write_command_options(out, cmd) out.puts ".br" write_corresponding_command(out, cmd) end
Returns the description for the command
# File lib/ctioga2/commands/doc/man.rb, line 210 def write_command_description(out, cmd) mup = MarkedUpText.new(@doc, cmd.long_description) out.puts markup_to_man(mup.elements) end
Displays the optional arguments for the given command
# File lib/ctioga2/commands/doc/man.rb, line 216 def write_command_options(out, cmd) if cmd.has_options? # .map {|x| "/#{x}="} ??? Does not seem to help much options = cmd.optional_arguments.keys.sort.join(' ') out.puts ".B Optional arguments:\n.I #{options}" end end
Writes a signature (ie the option specification) for the command
# File lib/ctioga2/commands/doc/man.rb, line 199 def write_command_signature(out, cmd) short, long, dummy = cmd.option_strings long, *args = long.split(/\s+/) args = " \\fI#{args.join(' ')}\\fR" out.puts ".B %s%s%s%s" % [ short, (short ? ", " : ""), long, args ] # Blacklist commands whose signature we wrote. @cmd_exclude[cmd] = true end
Writes out all commands to out.
# File lib/ctioga2/commands/doc/man.rb, line 146 def write_commands(out) for group in @groups next if @group_exclude[group] write_group(out, group) end end
Displays the corresponding 'file' command
# File lib/ctioga2/commands/doc/man.rb, line 225 def write_corresponding_command(out, cmd) arguments = cmd.arguments.map {|a| a.displayed_name}.join(',') if cmd.has_options? arguments += ",option=..." end out.puts ".B Corresponding command:\n.I #{cmd.name}(#{arguments})" end
Writes out a single group
# File lib/ctioga2/commands/doc/man.rb, line 154 def write_group(out, group) write_group_name(out, group) write_group_description(out, group) write_group_commands(out, group) end
Writes the remaining commands of a group
# File lib/ctioga2/commands/doc/man.rb, line 175 def write_group_commands(out, group) for cmd in @cmds[group].sort {|a,b| a.long_option <=> b.long_option } next if @cmd_exclude[cmd] out.puts out.puts ".TP #{ManIndent}" write_command(out, cmd) end # Now blacklist the group @group_exclude[group] = true end
Writes the description of a group.
# File lib/ctioga2/commands/doc/man.rb, line 168 def write_group_description(out, group) out.puts out.puts markup_to_man(group.description, false) out.puts end
Writes the name of a group
# File lib/ctioga2/commands/doc/man.rb, line 161 def write_group_name(out, group) out.puts out.puts ".SS #{group.name}" out.puts end
# File lib/ctioga2/commands/doc/man.rb, line 242 def write_type(out, type, indent = "") out.puts ".TP #{indent}" out.puts ".I #{type.name}" out.puts markup_to_man(type.description) end
Writes documentation about all the types known to ctioga.
# File lib/ctioga2/commands/doc/man.rb, line 234 def write_types(out) first = true for n, t in @doc.types.sort write_type(out,t, first ? "8" : "") first = false end end