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

doc[RW]

The Doc object Help2Man should be working on.

Public Class Methods

new(doc) click to toggle source
# File lib/ctioga2/commands/doc/man.rb, line 35
def initialize(doc)
  @doc = doc
end

Public Instance Methods

write_manual_page(version, input, out = STDOUT) click to toggle source

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

header_string(version, file) click to toggle source

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
markup_to_man(items, inside_cmds = true) click to toggle source

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
write_command(out, cmd) click to toggle source
# 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
write_command_description(out, cmd) click to toggle source

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
write_command_options(out, cmd) click to toggle source

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
write_command_signature(out, cmd) click to toggle source

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
write_commands(out) click to toggle source

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
write_corresponding_command(out, cmd) click to toggle source

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
write_group(out, group) click to toggle source

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
write_group_commands(out, group) click to toggle source

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
write_group_description(out, group) click to toggle source

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
write_group_name(out, group) click to toggle source

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
write_type(out, type, indent = "") click to toggle source
# 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
write_types(out) click to toggle source

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