ronn 0.6.6 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. data/CHANGES +34 -0
  2. data/INSTALLING +18 -0
  3. data/README.md +43 -69
  4. data/Rakefile +9 -10
  5. data/bin/ronn +66 -49
  6. data/config.ru +1 -1
  7. data/lib/ronn.rb +35 -9
  8. data/lib/ronn/document.rb +239 -135
  9. data/lib/ronn/index.rb +183 -0
  10. data/lib/ronn/roff.rb +48 -28
  11. data/lib/ronn/template.rb +22 -8
  12. data/lib/ronn/template/dark.css +1 -4
  13. data/lib/ronn/template/default.html +0 -2
  14. data/lib/ronn/template/man.css +12 -12
  15. data/lib/ronn/utils.rb +8 -0
  16. data/man/index.html +78 -0
  17. data/man/index.txt +15 -0
  18. data/man/{ronn.5 → ronn-format.7} +26 -30
  19. data/man/{ronn.5.ronn → ronn-format.7.ronn} +39 -39
  20. data/man/ronn.1 +47 -15
  21. data/man/ronn.1.ronn +53 -23
  22. data/ronn.gemspec +14 -8
  23. data/test/angle_bracket_syntax.html +4 -2
  24. data/test/basic_document.html +4 -2
  25. data/test/custom_title_document.html +1 -2
  26. data/test/definition_list_syntax.html +4 -2
  27. data/test/dots_at_line_start_test.roff +10 -0
  28. data/test/dots_at_line_start_test.ronn +4 -0
  29. data/test/entity_encoding_test.html +24 -2
  30. data/test/entity_encoding_test.roff +41 -1
  31. data/test/entity_encoding_test.ronn +17 -0
  32. data/test/index.txt +8 -0
  33. data/test/markdown_syntax.html +5 -3
  34. data/test/markdown_syntax.roff +4 -4
  35. data/test/middle_paragraph.html +4 -2
  36. data/test/missing_spaces.roff +3 -0
  37. data/test/section_reference_links.html +4 -2
  38. data/test/{ronn_test.rb → test_ronn.rb} +18 -5
  39. data/test/{document_test.rb → test_ronn_document.rb} +59 -8
  40. data/test/test_ronn_index.rb +73 -0
  41. data/test/titleless_document.html +7 -2
  42. data/test/titleless_document.ronn +3 -2
  43. data/test/underline_spacing_test.roff +5 -0
  44. metadata +30 -14
  45. data/man/ronn.7 +0 -168
  46. data/man/ronn.7.ronn +0 -120
data/man/ronn.7.ronn DELETED
@@ -1,120 +0,0 @@
1
- ronn -- the opposite of roff
2
- ============================
3
-
4
- ## DESCRIPTION
5
-
6
- Ronn is a text format and toolchain for creating UNIX manpages. It converts
7
- markdown to standard UNIX roff manpages and formatted HTML manuals for the web.
8
-
9
- The source format includes all of Markdown but has a more rigid structure and
10
- includes extensions that provide features commonly found in manpages (definition
11
- lists, link notation, etc.). The ronn(5) manual page defines the format in
12
- detail.
13
-
14
- ## DOCUMENTATION
15
-
16
- The `.ronn` files located under the `man/` directory show off a wide range of
17
- ronn capabilities and are the source of Ronn's own documentation. The source
18
- files and generated HTML / roff output files are available at:
19
-
20
- * [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) -
21
- convert markdown files to manpages.<br>
22
- [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.1.ronn),
23
- [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.1)
24
-
25
- * [ronn(5)](http://rtomayko.github.com/ronn/ronn.5) -
26
- markdown-based text format for authoring manpages<br>
27
- [source file](http://github.com/rtomayko/ronn/blob/master/man/ronn.5.ronn),
28
- [roff output](http://github.com/rtomayko/ronn/blob/master/man/ronn.5)
29
-
30
- ## INSTALL
31
-
32
- Install with Rubygems:
33
-
34
- $ [sudo] gem install ronn
35
- $ ronn --help
36
-
37
- Or, clone the git repository:
38
-
39
- $ git clone git://github.com/rtomayko/ronn.git
40
- $ PATH=ronn/bin:$PATH
41
- $ ronn --help
42
-
43
- ## BASIC USAGE
44
-
45
- Build roff and HTML output files for one or more input files:
46
-
47
- $ ronn man/ronn.5.ronn
48
- roff: man/ronn.5
49
- html: man/ronn.5.html
50
-
51
- View a roff manpage with man(1):
52
-
53
- $ man man/ronn.5
54
-
55
- Generate only a standalone HTML version of one or more files:
56
-
57
- $ ronn --html man/markdown.5.ronn
58
- html: man/markdown.5.html
59
-
60
- Build roff versions of all ronn files in a directory:
61
-
62
- $ ronn --roff man/*.ronn
63
-
64
- View a ronn file as if it were a manpage without building intermediate files:
65
-
66
- $ ronn --man man/markdown.5.ronn
67
-
68
- The [ronn(1)](http://rtomayko.github.com/ronn/ronn.1) manual page includes
69
- comprehensive documentation on `ronn` command line options.
70
-
71
- ## ABOUT
72
-
73
- Some people say UNIX manual pages are a poor and outdated style of
74
- documentation. I disagree:
75
-
76
- - Man pages follow a well defined structure that's immediately familiar. This
77
- provides developers with a useful starting point when documenting new tools,
78
- libraries, and formats.
79
-
80
- - Man pages get to the point. Because they're written in an inverted style, with
81
- a SYNOPSIS section followed by additional detail, prose and references to
82
- other sources of information, man pages provide the best of both cheat sheet
83
- and reference style documentation.
84
-
85
- - Man pages have extremely -- unbelievably -- limited text formatting
86
- capabilities. You get a couple of headings, lists, bold, underline and no
87
- more. This is a feature.
88
-
89
- - Although two levels of section hierarchy are technically supported, most man
90
- pages use only a single level. Unwieldy document hierarchies complicate
91
- otherwise good documentation. Feynman covered all of physics -- heavenly
92
- bodies through QED -- with only two levels of document hierarchy (_The Feynman
93
- Lectures on Physics_, 1970).
94
-
95
- - Man pages have a simple referencing syntax; e.g., sh(1), fork(2), markdown(7).
96
- HTML versions can use this to generate links between pages.
97
-
98
- - The classical terminal man page display is typographically well thought out.
99
- Big bold section headings, justified monospace text, nicely indented
100
- paragraphs, intelligently aligned definition lists, and an informational
101
- header and footer.
102
-
103
- Unfortunately, figuring out how to create a manpage is a fairly tedious process.
104
- The roff/man macro languages are highly extensible, fractured between multiple
105
- dialects, and include a bunch of device specific stuff irrelevant to modern
106
- publishing tools.
107
-
108
- Ronn aims to address many of the issues with manpage creation while preserving
109
- the things that makes manpages a great form of documentation.
110
-
111
- ## COPYING
112
-
113
- Ronn is Copyright (C) 2009 [Ryan Tomayko](http://tomayko.com/about)<br>
114
- See the file COPYING for information of licensing and distribution.
115
-
116
- ## SEE ALSO
117
-
118
- [ronn(1)](http://rtomayko.github.com/ronn/ronn.1),
119
- [ronn(5)](http://rtomayko.github.com/ronn/ronn.5),
120
- markdown(5)