ANNOUNCE: RosettaMan man to pod module 
Author Message
 ANNOUNCE: RosettaMan man to pod module

RosettaMan, which converts formatted manual pages to a number of text
processor source formats, now has an output module for Perl 5's pod
format.  It isn't perfect.  For bold, italics, and bold-italics
characters, section and subsection headers, and links to other manual
pages, it very nearly is.  With lists ("=item") and indented sections
("=over") it makes mistakes.  For a perfect conversion you usually
have to edit the result from RosettaMan.  Still, RosettaMan does
enough work as to make practicable the conversion of long manual
pages.  Appended to the end of this post is an unretouched conversion
of gmake's manual page to pod format.

Tom Phelps

--------------------------------------------------

A new version of RosettaMan is now available for anonymous ftp at
ftp.cs.berkeley.edu in the /ucb/people/phelps/tcltk directory.  You
may obtain it with the following commands:

ftp ftp.cs.berkeley.edu
cd /ucb/people/phelps/tcltk
binary
get rman.tar.Z ("rman.tar.Z" links to the latest, numbered version)

RosettaMan is a filter for UNIX manual pages.  It takes as input man
pages formatted for a variety of UNIX flavors (not [tn]roff source)
and produces as output a variety of file formats.  Currently
RosettaMan accept man pages as formatted by the following flavors of
UNIX: Hewlett-Packard HP-UX, AT&T System V, SunOS, Sun Solaris, OSF/1,
DEC Ultrix, SGI IRIX, Linux; and produces output for the following
formats: printable ASCII only (with page headers and footers
stripped), section and subsection headers only, TkMan, [tn]roff,
Ensemble, HTML, LaTeX, RTF, Perl 5 pod.

RosettaMan improves upon other man page filters in several ways: (1) its
analysis recognizes the structural pieces of man pages, enabling high
quality output, (2) its modular structure permits easy augmentation of
output formats, (3) it accepts man pages formatted with the variant
macros of many different flavors of UNIX, and (4) it doesn't require
modification of or cooperation with any other program.

RosettaMan is a rewrite of TkMan's man page filter, called bs2tk.  (If
you haven't heard about TkMan, a hypertext man page browser written in
Tcl/Tk, you can grab it via anonymous ftp from the same place as
RosettaMan.)  Whereas bs2tk generated output only for TkMan,
RosettaMan generalizes the process so that the analysis can be
leveraged to new output formats.  A single analysis engine recognizes
section heads, subsection heads, body text, lists(!), references to
other man pages, boldface, italics, bold italics, special characters
(like bullets) and strips out page headers and footers.  The engine
sends signals to the selected output functions so that an improvement
of the engine improves the quality of output of all of them.  Output
format functions are easy to add, and thus far average about about 75
lines of C code each.

A note for HTML consumers: This filter does real (heuristic)
parsing--no <PRE>!  Man page references are turned into hypertext
links.  The file <A HREF="ftp://ftp.cs.berkeley.edu/ucb/people/phelps/tcl/sgi-ls.1.html">
is an example of the quality of output produced entirely automatically
(no retouching) by RosettaMan.  Several people have extended Mosaic to
format man pages on the fly.  Check the README file in the contrib
directory for a list.

--------------------------------------------------

=head1 NAME

gmake - GNU make utility to maintain groups of programs

=head1 B<SYNOPSIS>

B<gmake> [ B<-f> makefile ] [ option ] ...  target ...

=head1 B<WARNING>

This man paage is an extract of the documentation of I<GNU> I<make> . It is
updated only occasionally, because the GNU project does not use nroff.
For complete, current documentation, refer to the Info file B<gmake> or
the DVI file B<gmake.dvi> which are made from the Texinfo source file
B<gmake.texinfo>.

=head1 B<DESCRIPTION>

The purpose of the I<gmake> utility is to determine automatically which
pieces of a large program need to be recompiled, and issue the
commands to recompile them.  This manual describes the GNU
implementation of I<make>, which was written by Richard Stallman and
Roland McGrath.  Our examples show C programs, since they are most
common, but you can use I<gmake> with any programming language whose
compiler can be run with a shell command.  In fact, I<gmake> is not
limited to programs.  You can use it to describe any task where some
files must be updated automatically from others whenever the others
change.  To prepare to use I<gmake>, you must write a file called the
I<makefile> that describes the relationships among files in your program,
and the states the commands for updating each file.  In a program,
typically the executable file is updated from object files, which are
in turn made by compiling source files.  Once a suitable makefile
exists, each time you change some source files, this simple shell
command:

     B<gmake>

suffices to perform all necessary recompilations.  The I<gmake> program
uses the makefile data base and the last-modification times of the
files to decide which of the files need to be updated.  For each of
those files, it issues the commands recorded in the data base.  I<gmake>
executes commands in the I<makefile> to update one or more target I<names>,
where I<name> is typically a program.  If no B<-f> option is present, I<gmake>
will look for the makefiles I<GNUmakefile>, I<makefile>, and I<Makefile>, in
that order.  Normally you should call your makefile either I<makefile> or
I<Makefile>.  (We recommend I<Makefile> because it appears prominently near
the beginning of a directory listing, right near other important files
such as I<README>.) The first name checked, I<GNUmakefile>, is not
recommended for most makefiles.  You should use this name if you have
a makefile that is specific to GNU I<make>, and will not be understood by
other versions of I<make>.  If I<makefile> is `-', the standard input is
read.  I<gmake> updates a target if it depends on prerequisite files that
have been modified since the target was last modified, or if the
target does not exist.

=head1 B<OPTIONS>

B<-b>

=over 5

=item B<-m>

These options are ignored for compatibility with other versions
of I<make>.

=item B<-C> I<dir>

Change to directory I<dir> before reading the makefiles or doing
anything else.  If multiple B<-C> options are specified, each is
interpreted relative to the previous one: B<-C> / B<-C> etc is
equivalent to B<-C> /etc.  This is typically used with recursive
invocations of I<gmake>.

=item B<-d>

Print debugging information in addition to normal processing.
The debugging information says which files are being considered
for remaking, which file-times are being compared and with what
results, which files actually need to be remade, which implicit
rules are considered and which are applied---everything
interesting about how I<gmake> decides what to do.

=item B<-e>

Give variables taken from the environment precedence over
variables from makefiles.

=item B<-f> I<file>

Use I<file> as a makefile.

=item B<-i>

Ignore all errors in commands executed to remake files.

=item B<-I> I<dir>

Specifies a directory I<dir> to search for included makefiles.  If
several B<-I> options are used to specify several directories, the
directories are searched in the order specified.  Unlike the
arguments to other flags of I<gmake>, directories given with B<-I>
flags may come directly after the flag: B<-Idir> is allowed, as well
as B<-I> I<dir>.  This syntax is allowed for compatibility with the C
preprocessor's B<-I> flag.

=item B<-j> I<jobs>

Specifies the number of jobs (commands) to run simultaneously.
If there is more than one B<-j> option, the last one is effective.
If the B<-j> option is given without an argument, I<gmake> will not
limit the number of jobs that can run simultaneously.

=item B<-k>

Continue as much as possible after an error.  While the target
that failed, and those that depend on it, cannot be remade, the
other dependencies of these targets can be processed all the
same.

=item B<-l>

=item B<-l> I<load>

Specifies that no new jobs (commands) should be started if there
are others jobs running and the load average is at least I<load> (a
floating-point number).  With no argument, removes a previous
load limit.

=item B<-n>

Print the commands that would be executed, but do not execute
them.

=item B<-o> I<file>

Do not remake the file I<file> even if it is older than its
dependencies, and do not remake anything on account of changes in
I<file>.  Essentially the file is treated as very old and its rules
are ignored.

=item B<-p>

Print the data base (rules and variable values) that results from
reading the makefiles; then execute as usual or as otherwise
specified.  This also prints the version information given by the
B<-v> switch (see below).  To print the data base without trying to
remake any files, use B<gmake> B<-p> B<-f>/I<dev>/I<null>.

=item B<-q>

``Question mode''.  Do not run any commands, or print anything;
just return an exit status that is zero if the specified targets
are already up to date, nonzero otherwise.

=item B<-r>

Eliminate use of the built-in implicit rules.  Also clear out the
default list of suffixes for suffix rules.

=item B<-s>

Silent operation; do not print the commands as they are executed.

=item B<-S>

Cancel the effect of theB< ->k option.  This is never necessary
except in a recursive I<gmake> where B<-k> might be inherited from the
top-level I<gmake> via MAKEFLAGS or if you set B<-k> in MAKEFLAGS in
your environment.

=item B<-t>

Touch files (mark them up to date without really changing them)
instead of running their commands.  This is used to pretend that
the commands were done, in order to fool future invocations of
I<gmake>.

=item B<-v>

Print the version of theI< gmak>e program plus a copyright, a list
of authors and a notice that there is no warranty.  After this
information is printed, processing continues normally.  To get
this information without doing anything else, use B<gmake> B<-v>
B<-f>/I<dev>/I<null>.

=item B<-w>

Print a message containing the working directory before and after
other processing.  This may be useful for tracking down errors
from complicated nests of recursive I<gmake> commands.

=item B<-W> I<file>

Pretend that the target I<file> has just been modified.  When used
with the B<-n> flag, this shows you what would happen if you were to
modify that file.  Without B<-n>, it is almost the same as running a
I<touch> command on the given file before running I<gmake>, except that
the modification time is changed only in the imagination of
I<gmake>.

=back

=head1 B<SEE> B<ALSO>

/usr/local/doc/gnumake.dvi
                    I<The> I<GNU> I<Make> I<Manual>

=head1 B<BUGS>

See the chapter `Problems and Bugs' in I<The> I<GNU> I<Make> I<Manual> .

=head1 B<AUTHOR>

This manual page contributed by Dennis Morse of Stanford University.
It has been reworked by Roland McGrath.
--



Mon, 28 Apr 1997 12:27:36 GMT  
 
 [ 1 post ] 

 Relevant Pages 

1. ANNOUNCE: RosettaMan 2.0, a manual page converter

2. ANNOUNCE: Emacs lisp TinyPerl.el plug-in module (POD mode)

3. Announce: Emacs TinyPerl.el module (POD mode)

4. info on pod besides man perlpod

5. Confused - pod and man files

6. _62 and Pod::Man possible bug

7. tk man, perl man, and man servers

8. Pod::Filter, Pod::Usage, and Pod::PlainText now on CPAN

9. Pod Problems (using =pod, nesting fonts, and Pod::Text)

10. Module.pod and Module.pm co-existence (was: Perldoc and Perlfaq)

11. ANNOUNCE: Pod::Html patch providing relative URLs

12. Where to upload/announce an emacs pod-mode?

 

 
Powered by phpBB® Forum Software