Class: Ronn::Document

Inherits:
Object
  • Object
show all
Defined in:
lib/ronn/document.rb

Overview

The Document class can be used to load and inspect a ronn document and to convert a ronn document into other formats, like roff or HTML.

Ronn files may optionally follow the naming convention: “<name>.<section>.ronn”. The <name> and <section> are used in generated documentation unless overridden by the information extracted from the document’s name section.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path = nil, attributes = {}, &block) ⇒ Document

Create a Ronn::Document given a path or with the data returned by calling the block. The document is loaded and preprocessed before the intialize method returns. The attributes hash may contain values for any writeable attributes defined on this class.



53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/ronn/document.rb', line 53

def initialize(path=nil, attributes={}, &block)
  @path = path
  @basename = path.to_s =~ /^-?$/ ? nil : File.basename(path)
  @reader = block || Proc.new { |f| File.read(f) }
  @data = @reader.call(path)
  @name, @section, @tagline = nil
  @manual, @organization, @date = nil
  @fragment = preprocess
  @styles = %w[man]

  attributes.each { |attr_name,value| send("#{attr_name}=", value) }
end

Instance Attribute Details

#data ⇒ Object (readonly)

Returns the value of attribute data.



18
19
20
 
# File 'lib/ronn/document.rb', line 18

def data
  @data
end

#date ⇒ Object

The date the man page was published. If not set explicitly, this is the file’s modified time or, if no file is given, the current time.



44
45
46
 
# File 'lib/ronn/document.rb', line 44

def date
  @date
end

#manual ⇒ Object

The manual this document belongs to; center displayed in the header.



36
37
38
 
# File 'lib/ronn/document.rb', line 36

def manual
  @manual
end

#name ⇒ Object

Returns the manual page name based first on the document’s contents and then on the path name.



24
25
26
 
# File 'lib/ronn/document.rb', line 24

def name
  @name
end

#organization ⇒ Object

The name of the group, organization, or individual responsible for this document; displayed in the left portion of the footer.



40
41
42
 
# File 'lib/ronn/document.rb', line 40

def organization
  @organization
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



18
19
20
 
# File 'lib/ronn/document.rb', line 18

def path
  @path
end

#section ⇒ Object

Returns the manual page section based first on the document’s contents and then on the path name.



28
29
30
 
# File 'lib/ronn/document.rb', line 28

def section
  @section
end

#styles ⇒ Object

Array of style modules to apply to the document.



47
48
49
 
# File 'lib/ronn/document.rb', line 47

def styles
  @styles
end

#tagline ⇒ Object

Single sentence description of the thing being described by this man page; displayed in the NAME section.



32
33
34
 
# File 'lib/ronn/document.rb', line 32

def tagline
  @tagline
end

Instance Method Details

#basename(type = nil) ⇒ Object

Generate a file basename of the form “<name>.<section>.<type>” for the given file extension. Uses the name and section from the source file path but falls back on the name and section defined in the document.



70
71
72
73
74
 
# File 'lib/ronn/document.rb', line 70

def basename(type=nil)
  type = nil if ['', 'roff'].include?(type.to_s)
  [path_name || @name, path_section || @section, type].
  compact.join('.')
end

#convert(format) ⇒ Object

Convert the document to :roff, :html, or :html_fragment and return the result as a string.



150
151
152
 
# File 'lib/ronn/document.rb', line 150

def convert(format)
  send "to_#{format}"
end

#name? ⇒ Boolean

Truthful when the name was extracted from the name section of the document.

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/ronn/document.rb', line 108

def name?
  !name.nil?
end

#path_for(type = nil) ⇒ Object

Construct a path for a file near the source file. Uses the Document#basename method to generate the basename part and appends it to the dirname of the source document.



79
80
81
82
83
84
85
 
# File 'lib/ronn/document.rb', line 79

def path_for(type=nil)
  if @basename
    File.join(File.dirname(path), basename(type))
  else
    basename(type)
  end
end

#path_name ⇒ Object

Returns the <name> part of the path, or nil when no path is available. This is used as the manual page name when the file contents do not include a name section.



90
91
92
 
# File 'lib/ronn/document.rb', line 90

def path_name
  @basename[/^[^.]+/] if @basename
end

#path_section ⇒ Object

Returns the <section> part of the path, or nil when no path is available.



96
97
98
 
# File 'lib/ronn/document.rb', line 96

def path_section
  $1 if @basename.to_s =~ /\.(\d\w*)\./
end

#section? ⇒ Boolean

True when the section number was extracted from the name section of the document.

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/ronn/document.rb', line 120

def section?
  !section.nil?
end

#section_heads ⇒ Object

Retrieve a list of top-level section headings in the document and return as an array of [id, text] tuples, where id is the element’s generated id and text is the inner text of the heading element.



136
137
138
139
140
 
# File 'lib/ronn/document.rb', line 136

def section_heads
  parse_html(to_html_fragment).search('h2[@id]').map do |heading|
    [heading.attributes['id'], heading.inner_text]
  end
end

#to_html ⇒ Object

Convert the document to HTML and return the result as a string.



168
169
170
171
172
173
174
175
176
177
178
 
# File 'lib/ronn/document.rb', line 168

def to_html
  if layout = ENV['RONN_LAYOUT']
    if !File.exist?(layout_path = File.expand_path(layout))
      warn "warn: can't find #{layout}, using default layout."
      layout_path = nil
    end
  end

  template = Ronn::Template.new(self)
  template.render(layout_path || 'default')
end

#to_html_fragment(wrap_class = 'mp') ⇒ Object

Convert the document to HTML and return the result as a string. The HTML does not include <html>, <head>, or <style> tags.



183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'lib/ronn/document.rb', line 183

def to_html_fragment(wrap_class='mp')
  wrap_class = nil if wrap_class.to_s.empty?
  buf = []
  buf << "<div class='#{wrap_class}'>" if wrap_class
  if name? && section?
    buf << "<h2 id='NAME'>NAME</h2>"
    buf << "<p><code>#{name}</code> - #{tagline}</p>"
  elsif tagline
    buf << "<h1>#{[name, tagline].compact.join(' - ')}</h1>"
  end
  buf << @fragment.to_s
  buf << "</div>" if wrap_class
  buf.join("\n")
end

#to_roff ⇒ Object

Convert the document to roff and return the result as a string.



155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/ronn/document.rb', line 155

def to_roff
  RoffFilter.new(
    to_html_fragment(wrap_class=nil),
    name,
    section,
    tagline,
    manual,
    organization,
    date
  ).to_s
end