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
198
199
200
201
202
203
204
|
Since May 2002, Netpbm does not have traditional man pages for
documentation. BUT YOU CAN CONFIGURE NETPBM, IF YOU WANT, SO YOU GET
ESSENTIALLY THE SAME 'MAN' FUNCTION AS WITH A TRADITIONAL UNIX PACKAGE.
Netpbm's maintainer believes man pages are obsolete and too limiting,
and doesn't have time to maintain the documentation in multiple
formats. So instead of classic nroff man page format, the Netpbm
documentation is available as HTML, with one HTML file per program,
plus some others. The current user manual is accessible on the World
Wide Web at <http://netpbm.sourceforge.net/doc>, and if it's practical
for you, you should access it there instead of making a local copy.
This manual is always up to date. It is not maintained on a release
schedule like the source code is, but rather updated continuously.
The user manual describes past Netpbm function as well as the present,
so you can use the current manual with old Netpbm code.
INSTALLING A LOCAL COPY OF DOCUMENTATION
----------------------------------------
If accessing the manual on the World Wide Web is not convenient for you (for
example, if you want to access it from a computer that is not always connected
to the Internet), just make a local copy of the HTML files.
You can get the files from the Subversion repository using the Subversion
client program 'svn':
URL=https://svn.code.sf.net/p/netpbm/code/userguide
svn export $URL
This creates a directory "userguide" in your current directory containing
all the same files that are on the web site.
An alternative is just to copy the web site with something like GNU Wget.
However, the Sourceforge web server has limitations on how much you can
download. In a February 2012 experiment, Sourceforge started refusing HTTP
requests (with an Internal Server Error indication and a message saying there
had been too many requests) before all the files could be fetched. But you
can use Wget controls to fool Sourceforge. The following worked in January
2016:
wget --wait=1 --random-wait \
--recursive --relative http://netpbm.sourceforge.net/doc/
GETTING COMMAND HELP WITH A "MAN" COMMAND
-----------------------------------------
You can get the same quick access to program documentation with this
HTML setup as with traditional man pages, using the Manweb program.
This works whether you use the www copy or a local copy of the HTML
files. Manweb is distributed with Netpbm. With Manweb and Netpbm
installed and configured appropriately (see below), you can type
man netpbm
and get the top level page of the Netpbm user manual (with hyperlinks to
all the other pages), or
man netpbm ppmtogif
or
man ppmtogif
to go straight to the Ppmtogif documentation.
Installnetpbm normally installs Manweb and the netpbm.url file that
Manweb needs to find the Netpbm documentation. Through the Configure
dialog, or editing config.mk, you determine whether Manweb
accesses the master web copy or a local copy you installed.
Installnetpbm installs the program as 'manweb'. If you want to invoke
it as 'man', you'll have to set that up yourself. Perhaps with a
symbolic link from 'man' to 'manweb'. Note that 'manweb' is mostly
backward compatible with 'man' so that this is a reasonable thing to
do. Manweb can find documentation on the web, in HTML files, in GNU
info files, and in traditional man pages.
In a standard installation of Netpbm, Installnetpbm also creates a
traditional man page for every Netpbm program it installs, but the man
page just tells you to go to the HTML file. This way, even if the "man"
program isn't capable of reading the HTML documentation and even if the
user doesn't know specifically where Netpbm documentation lives, he isn't
stranded without information.
VIEWING NETPBM DOC WITH TRADITIONAL MAN PROGRAM
-----------------------------------------------
Some people want to be able to access the Netpbm documentation with an
existing man program that doesn't know HTML. You can install the
documentation that way, with some loss of quality. There are two
ways:
1) convert the HTML to troff with the 'makeman' program in the
'buildtools' directory of the Netpbm source tree. This is a
Python program.
2) convert the HTML to formatted plain text (suitable as man "cat"
pages) with the 'makecat' program in the 'buildtools' directory
of the Netpbm source tree. This program uses the dump feature
of the lynx text web browser for conversion.
The "loss of quality" mentioned above is because:
- The classic Unix manual format isn't as expressive as the
worldwide web format; you can't convert down losslessly.
- There is less maintenance effort put into maintaining the
secondary non-web format. It requires certain idioms to be
followed in the HTML source and lists of man pages to be
separately maintained. This maintenance is essentially done on a
fault basis -- when someone notices the Unix man pages aren't
right, he fixes something.
Bear in mind that the person who writes most of the Netpbm
documentation updates never sees the troff versions; he uses
Manweb, which renders directly from the HTML.
Also, these methods require manual effort, and technical
understanding, on your part to set up. Setting it up is too complex
for an automated process to do it for you with any significant
integrity. The examples are guidelines and may not work literally
in your situation.
MAKING TROFF MAN PAGES
----------------------
1. Start work at the top-level directory of the source package.
2. Download the HTML files using the subversion command.
The downloaded files will go into "./userguide/".
svn export https://svn.code.sf.net/p/netpbm/code/userguide
3. Create a work directory named "netpbmdoc". The troff man pages,
as they are converted from HTML pages by the makeman utility, will
be written here.
mkdir netpbmdoc
cd netpbmdoc
make USERGUIDE=../userguide/ -f ../buildtools/manpage.mk manpages
USERGUIDE is the directory containing the input HTML pages. Keep
it intact until installation is complete.
4. Install the troff man pages, with MANDIR set up appropriately
to the destination.
MANDIR and MANDIR/{man1,man3,man5} must be existing directories.
The install step usually requires superuser permissions.
make MANDIR=/usr/local/netpbm/man USERGUIDE=../userguide/ \
-f ../buildtools/manpage.mk installman
cd ../
rm -rf netpbmdoc
5. Adjust MANPATH if necessary and try showing one manual page.
man pamflip
MAKING CAT PAGES
----------------
As with the above example for troff man pages, start at the top-level
directory of the source package.
svn export https://svn.code.sf.net/p/netpbm/code/userguide
cd ./userguide
../buildtools/makecat *.html
cp *.1 /usr/man/cat1/ # Usually requires superuser permission
The makecat utility reads files from the current directory and writes
the results into the same directory. As noted above, it requires lynx
<http://lynx.invisible-island.net/>.
DOCBOOK
-------
You can turn the Netpbm user manual into Docbook XML pages using Doclifter.
Because Doclifter works on troff pages, you have to convert the documentation
down to troff first, which means the Docbook pages are of lower quality than
the master HTML documentation.
To create Docbook XML, do as follows:
mkdir netpbmdoc
cd netpbmdoc
make USERGUIDE=../userguide/ -f ../buildtools/manpage.mk xmlpages
The 'make' executes the HTML to troff conversion step automatically. For the
troff to XML step, there are problems that have not been completely worked
out; conversion of several files will fail.
There is no equivalent for 'make installman' for the Docbook XML pages.
|
