forked from utPLSQL/utPLSQL
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathwritedoc.html
More file actions
149 lines (125 loc) · 5.75 KB
/
Copy pathwritedoc.html
File metadata and controls
149 lines (125 loc) · 5.75 KB
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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>How to add to the utPLSQL documentation set</title>
</head>
<body>
<!-- $Id$ -->
<h2>Writing Documentation</h2>
<p>
The utPLSQL documentation is built from a series of simple HTML files in the
src directory. These files have none of the navigation bars, logos or
next/previous links which appear in the final documentation. They are also
stripped of font, color and style information at compile-time to let the
stylesheet (utplsql.css) determine the overall look-and-feel.
</p>
<p>
Like the code, the documentation is held within GIT.
Changes should be made to the documentation/src directory.
Details on how to change and submit the changes back to the
project can be found in the <a href = "https://github.com/utPLSQL/utPLSQL/blob/master/CONTRIBUTING.md">CONTRIBUTING.md</a>
</p>
<h3>The HTML Files</h3>
<p>
As described above, the base files in the src directory are used to generate the final
product. To add new documentation to one of these files, or to correct errors,
simply edit it. It makes sense to follow the layout that is already present in the
file, adding links at the top of the page where appropriate. The HTML should be
kept simple, so use the relevant header styles (<H1>...<H6>) to label your sections
and subsections, use <pre> to mark sections of code etc. Let the stylesheet
do the work of setting the colors and fonts.
</p>
<p>
If you are adding an entirely new file to the documentation, use the file
<code>template.html</code> as a basis. This contains the relevant comment
lines which tell the scripts which parts of the file to use
(see the <a href="#comment">note below</a>). Finally, you will need to
edit map.txt to ensure that the file is linked from the other pages in
the documentation. This is described in the next section.
</p>
<h3>The Control Files</h3>
<p>
The files are compiled into a documentation set situated in the top-level
documentation directory using the 3 control files: map.txt, authors.txt and copyright_years.txt.
The first of these is the driving file, giving a list of the files to be
included. The second gives a list of authors to be included in the copyright
notice on each page and referenced in the Meta tags (this is for
historical reasons and lists the original contributors of the
documentation - to keep it in line with the policy for source-code, all
future contributions will go under the name of "the utPLSQL Project"). The
third file lists the years for the copyright statement - i.e. years when
significant changes were published.
</p>
<p>The format of map.txt is as follows:</p>
<pre>
# Any line starting with a # is
# considered a comment
#
index.html,Home*
started.html,Getting Started*
another.html,Further Docs
another2.html,Yet more docs
</pre>
<p>
Each line consists of the filename to be included and the title of the page,
separated with a comma. Any file whose title is followed by an asterisk is
considered the start of a new section. This means a link to the file will
appear in the navigation bar at the top of each page and it will appear in
bold in the document map. Note that the document map itself does not appear
in map.txt, but is always added at the end and is considered a new section.
This page is entirely generated at compile-time.
</p>
<p>
To add a new page to the documentation, simply add it to this file in the
correct position. Note that generally you will not be adding a new section!
</p>
<p>The format of authors.txt is as follows:</p>
<pre>
# Again, lines starting # are ignored
#
Steven Feuerstein,steven@stevenfeuerstein.com
Chris Rimmer,c@24.org.uk
A N Other,ano@ther.net
</pre>
<p>
Each line in this file simply gives the name of the author and their email
address, separated with a comma. So if you've made a contribution and your name
is not listed, add it!
</p>
<p>The format of copyright_years.txt is as follows:</p>
<pre>
# Again, lines starting # are ignored
#
2000-2005
2014
</pre>
<p>
Each line will be separated by a comma in the copyright statement, so the
above will generate: "2000-2005, 2014"
</p>
<h3>The Scripts</h3>
<p>
The Perl script used to build the documentation is build_docs.pl.
</p>
<p>
The script goes through each file listed in map.txt, cleans it up
and then adds logos, navigation bars, next/previous links,
copyright information etc. The resulting files are put in the top-level
documentation directory.
</p>
<p>
The "cleaning" strips the source HTML files down to the basics, removing
everything from the header and removing Javascript, fonts, color, etc. It
requires the HTML::TagFilter module which in turn also requires the
HTML::Parser and HTML::Tagset modules (all available from <a href="http://search.cpan.org">search.cpan.org</a>).
</p>
<p>
<i><a name="comment">NOTE</a>: Anything within a source file before the
<code><!-- Begin utPLSQL Body --></code> comment line and after the
<code><!-- End utPLSQL Body --></code> comment line is ignored.</i>
</p>
<p style="font-size:smaller">Copyright 2002, 2014 <a href="mailto:c@24.org.uk">Chris Rimmer</a> and the utPLSQL Project. All rights reserved</p>
</body>
</html>