Package: python-docutils / 0.12+dfsg-1

doc-debian-paths.diff Patch series | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
Description: change paths in documentation to match Debian's
 Change paths in documentation to match Debian's. Debian policy recommends not
 having extensions like .py on script names, and buildhtml seems too generic a
 name.
Author: Simon McVittie <smcv@debian.org>
Forwarded: not-needed
Last-Update: 2014-07-26

--- a/README.txt
+++ b/README.txt
@@ -11,8 +11,19 @@
 .. contents::
 
 
-Quick-Start
-===========
+Quick-Start on Debian systems
+=============================
+
+The reStructuredText tools are installed in the normal system path by the
+Debian ``python-docutils`` package. To convert reStructuredText to another
+format, use a shell command like::
+
+       rst2html /usr/share/doc/python-docutils/FAQ.txt ./FAQ.html
+
+See Usage_ below for details.
+
+Quick-Start on other systems
+============================
 
 This is for those who want to get up & running quickly.
 
@@ -283,6 +294,12 @@
 the front-end tools for details on options and arguments.  See
 Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.
 
+On a Debian system the included tools (with the exception of quicktest.py
+and the development tools in the dev/ directory) are installed into the
+normal system path, so you can run ``rst2html.py`` with a command like::
+
+    rst2html example.txt example.html
+
 The package modules are continually growing and evolving.  The
 ``docutils.statemachine`` module is usable independently.  It contains
 extensive inline documentation (in reStructuredText format of course).
--- a/docs/user/tools.txt
+++ b/docs/user/tools.txt
@@ -39,6 +39,10 @@
 used for the destination.  If no arguments are specified, the standard
 input (stdin) is used for the source as well.
 
+In Debian these tools are installed in the normal system path, without the
+``.py`` extension, according to Debian policy. 
+buildhtml.py_ is installed as rst-buildhtml.
+
 
 Getting Help
 ============
@@ -66,13 +70,15 @@
 :Parser: reStructuredText
 :Writers: HTML, PEP/HTML
 
+In Debian this tool is installed under the name rst-buildhtml.
+
 Use ``buildhtml.py`` to generate .html from all the .txt files
 (including PEPs) in each <directory> given, and their subdirectories
 too.  (Use the ``--local`` option to skip subdirectories.)
 
 Usage::
 
-    buildhtml.py [options] [<directory> ...]
+    rst-buildhtml [options] [<directory> ...]
 
 After unpacking the Docutils package, the following shell commands
 will generate HTML for all included documentation::
@@ -103,6 +109,8 @@
 :Parser: reStructuredText
 :Writer: HTML
 
+In Debian this front end is installed as rst2html.
+
 The ``rst2html.py`` front end reads standalone reStructuredText source
 files and produces HTML 4 (XHTML 1) output compatible with modern
 browsers that support cascading stylesheets (CSS).  A stylesheet is
@@ -112,13 +120,13 @@
 For example, to process a reStructuredText file "``test.txt``" into
 HTML::
 
-    rst2html.py test.txt test.html
+    rst2html test.txt test.html
 
 Now open the "``test.html``" file in your favorite browser to see the
 results.  To get a footer with a link to the source file, date & time
 of processing, and links to the Docutils project, add some options::
 
-    rst2html.py -stg test.txt test.html
+    rst2html -stg test.txt test.html
 
 
 Stylesheets
@@ -146,6 +154,8 @@
 :Parser: reStructuredText
 :Writer: PEP/HTML
 
+In Debian this front end is installed as rstpep2html.
+
 ``rstpep2html.py`` reads a new-style PEP (marked up with
 reStructuredText) and produces HTML.  It requires a template file and
 a stylesheet.  By default, it makes use of a "``pep-html-template``"
@@ -156,7 +166,7 @@
 For example, to process a PEP into HTML::
 
     cd <path-to-docutils>/docs/peps
-    rstpep2html.py pep-0287.txt pep-0287.html
+    rstpep2html pep-0287.txt pep-0287.html
 
 
 rst2s5.py
@@ -166,6 +176,8 @@
 :Parser: reStructuredText
 :Writer: S5/HTML
 
+In Debian this is installed as rst2s5.
+
 The ``rst2s5.py`` front end reads standalone reStructuredText source
 files and produces (X)HTML output compatible with S5_, the "Simple
 Standards-based Slide Show System" by Eric Meyer.  A theme is required
@@ -175,7 +187,7 @@
 For example, to process a reStructuredText file "``slides.txt``" into
 S5/HTML::
 
-    rst2s5.py slides.txt slides.html
+    rst2s5 slides.txt slides.html
 
 Now open the "``slides.html``" file in your favorite browser, switch
 to full-screen mode, and enjoy the results.
@@ -193,7 +205,7 @@
 the "``--theme-url``" option (for themes anywhere).  For example, the
 "medium-black" theme can be specified as follows::
 
-    rst2s5.py --theme medium-black slides.txt slides.html
+    rst2s5 --theme medium-black slides.txt slides.html
 
 The theme will be copied to the ``ui/medium-black`` directory.
 
@@ -276,11 +288,13 @@
 :Parser: reStructuredText
 :Writer: LaTeX2e
 
+In Debian this is installed as rst2latex.
+
 The ``rst2latex.py`` front end reads standalone reStructuredText
 source files and produces LaTeX2e output. For example, to process a
 reStructuredText file "``test.txt``" into LaTeX::
 
-    rst2latex.py test.txt test.tex
+    rst2latex test.txt test.tex
 
 The output file "``test.tex``" should then be processed with ``latex``
 or ``pdflatex`` to get a document in DVI, PostScript or PDF format for
@@ -299,6 +313,8 @@
 :Parser: reStructuredText
 :Writer: XML (Docutils native)
 
+In Debian this is installed as rst2xml.
+
 The ``rst2xml.py`` front end produces Docutils-native XML output.
 This can be transformed with standard XML tools such as XSLT
 processors into arbitrary final forms. An example is the xml2rst_ processor
@@ -317,6 +333,8 @@
 :Parser: reStructuredText
 :Writer: ODF/.odt
 
+In Debian this front end is installed as rst2odt.
+
 The ``rst2odt.py`` front end reads standalone reStructuredText
 source files and produces ODF/.odt files that can be read, edited,
 printed, etc with OpenOffice ``oowriter``
@@ -347,6 +365,8 @@
 :Parser: reStructuredText
 :Writer: Pseudo-XML
 
+In Debian this is installed as rst2pseudoxml.
+
 ``rst2pseudoxml.py`` is used for debugging the Docutils "Reader to
 Transform to Writer" pipeline.  It produces a compact pretty-printed
 "pseudo-XML", where nesting is indicated by indentation (no end-tags).
@@ -361,6 +381,9 @@
 :Parser: reStructuredText
 :Writer: N/A
 
+This tool is not currently installed by the Debian package;
+``apt-get source python-docutils`` if you need it.
+
 The ``quicktest.py`` tool is used for testing the reStructuredText
 parser.  It does not use a Docutils Reader or Writer or the standard
 Docutils command-line options.  Rather, it does its own I/O and calls