Am 2007-03-18 18:33:54, schrieb Douglas Allan Tutty: > I'll have to work on writing man pages. Since I don't fancy learning > roff just for that and I'm currently learning latex, I'll work on > learning to write man pages.
Copy the skeleton from an EXISTING manpage.
It is Easy since you need only:
.TH $command $mansection "$version" "$date $time" "$author"
.SH "$SECTION" => should be: NAME, SYNOPSIS, OPTIONS,
DESCRIPTION, EXIT STATUS, INPUT FILES,
OUTPUT, DIAGNOSTICS, AUTHOR, SEE ALSO,
BUGS, LICENSE
.SS "$SUBSECTION" => A subsection of the previous .SH
.PD => Blank line
.PP => Paragraph only
.TP => Paragraph with tag
.B => Bold
.I => Italic
.RS \ An independant area
.RE / (don't know how to eyplain in endglish)
Tags in text like
\fR $some_text \fP => \fR is for switching to Roman text
\fI $some_text \fP \fI is for switching to Italic text
\fP is for switching to the previos
text before \fR or \fI
\(lq and \(rq => left and right quote
\(ap ?> Apostrophe
\" An invisible comment up to the first Newline character
Also please see: man(7)
groff(7)
groff-char(7)
roff(7) => macros
Also you can use Macros which must be defined Aat the beginning of
the Manpage before the .TH header with
.de FN => Begin of the macro called FN
\fI\|\\$1\|\fP => put the text of $1 into \fI and \fP
.. => End of the macro
and then it can be called with:
.FN /etc/fstab
or you can do something like:
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
and then use:
.Vb
\. \fBSome thext here \fR
source \fBthe_file_to_source \fR
.Ve
> However, I haven't browsed the man pages for the base system (which I
> think would be the first priority). Is there an overall Debian plan for
> addressing the GFDL?
I think, it would be better to use the poularity-contest to determiner
which manpages to write first. Then after looking into each package
one after one, look, which command has NO manpage or undocumented(7).
If non-free manpages exist for the command look into it and then rewrite
it from scratch.
> I have a problem with the GNU stuff having basically a stub man page
> that says look at the info docs. Debian policy says that everything
> have a man page. Perhaps is needs to say ``complete'' man page.
They are manpages converted FROM info pages and they are realy badly
converted. So rewite it using the bad converted one as template.
> I'm quite interested in writing documentation. I don't do GUI stuff
I use "mc" which has nice Syntax Highlighting...
> much and since everyting can be made from a LaTex or dvi file and LaTex
> is very well documented, I'm learning LaTex. Basically, I want to build
> up my skills so that I can contribute. Is there a style guide for
> writing debian documentation?
I write only manpages and for this it is overkill to use any versions of
TeX.
> Also, if we take tar as an example, if the documentation as it is now
> can't be used and presumably the program has changed since the last
> version who's docs could be used, how does one write documentation on
> the differences without using the non-free docs as the only souce
> without violating the now-non-free licence?
Use the non-free one only as templates and rewite it with your own
words.
and do not forget to add the two last sections:
----8<------------------------------------------------------------------
.SH "AUTHOR"
This manpage was rewiten by Douglas Allan Tutty <[EMAIL PROTECTED]> for
the Debbian Project because the orginal one sucks with non-freenes.
.SH "LICENCE"
This manual page is under GNU GPL version 2.0.
----8<------------------------------------------------------------------
> One could say that its the job of the programmers, but they released the
> documentation under a non-free licence. Yet they are the ones that
> changed or added features since the previous version. I suppose someone
> could read the source, but I don't do C (or sh for that matter). Free
> software with non-free documentation seems backwards which is why I'm
> wondering what Debian's long-term plan is.
You can download the original (non-free) ones and hold it as versioned
reference. I now a new Version of the manpage apears, you can diff it.
BUT, YOU can tell the maintainer of the Package, that you want to
maintain the "dfsg" version of the manpage and please him, if a new
version apear, that he inform you immediatly BEFORE packing the NEW
version of the program so he can ADD your work to it, without
building an unneccesary package for it.
This works only, IF YOU take the responsability and respond very fast
to Package Maintainer requests if NEW versions arrive.
> Doug.
Thanks, Greetings and nice Day
Michelle Konzack
Systemadministrator
Tamay Dogan Network
Debian GNU/Linux Consultant
--
Linux-User #280138 with the Linux Counter, http://counter.li.org/
##################### Debian GNU/Linux Consultant #####################
Michelle Konzack Apt. 917 ICQ #328449886
50, rue de Soultz MSN LinuxMichi
0033/6/61925193 67100 Strasbourg/France IRC #Debian (irc.icq.com)
signature.pgp
Description: Digital signature
