[BACK]Return to manuals.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/manuals.7 between version 1.5 and 1.8

version 1.5, 2009/03/22 19:01:11 version 1.8, 2009/03/23 09:42:43
Line 1 
Line 1 
   .\" $Id$
   .\"
   .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   .\"
   .\" Permission to use, copy, modify, and distribute this software for any
   .\" purpose with or without fee is hereby granted, provided that the
   .\" above copyright notice and this permission notice appear in all
   .\" copies.
   .\"
   .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
   .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
   .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
   .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
   .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
   .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
   .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
   .\" PERFORMANCE OF THIS SOFTWARE.
   .\"
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt manuals 7  .Dt manuals 7
 .Os  .Os
Line 29  format or directory structure or device driver, it nee
Line 47  format or directory structure or device driver, it nee
 Prepare your composition environment by copying over the manual template  Prepare your composition environment by copying over the manual template
 from  from
 .Pa /usr/share/misc/mdoc.template .  .Pa /usr/share/misc/mdoc.template .
   .Pp
   If this file doesn't exist, bug your administrator.
 .Em \&Do not  .Em \&Do not
 start afresh or by copying another manual unless you know exactly what  start afresh or by copying another manual unless you know exactly what
 you're doing!  you're doing!
Line 72  to see the specific section manual (section 1, in this
Line 92  to see the specific section manual (section 1, in this
 .\" DISPLAY  .\" DISPLAY
 .Bd -literal -offset indent  .Bd -literal -offset indent
 % apropos myname  % apropos myname
 myname (1) - some description here  myname (1) - utility description
   myname (3) - library description
 % man \-s 1 myname  % man \-s 1 myname
 .Ed  .Ed
 .\" SUBSECTION  .\" SUBSECTION
Line 143  to version-control your work.  If you wish the last ch
Line 164  to version-control your work.  If you wish the last ch
 your document's date, use the following RCS tag for the date macro:  your document's date, use the following RCS tag for the date macro:
 .Pp  .Pp
 .Dl \&.Dd $Mdocdate$  .Dl \&.Dd $Mdocdate$
   .Pp
   If using version control, the first line in your manual should be a
   comment with the
   .Li $Id$
   rcs tag.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Viewing  .Ss Viewing
 mdoc documents may be paged to your terminal with traditional  mdoc documents may be paged to your terminal with traditional
Line 181  output:
Line 207  output:
 \&.1.txt:  \&.1.txt:
         mandoc -Tascii $< | col -b >$@          mandoc -Tascii $< | col -b >$@
 .Ed  .Ed
   .\" SUBSECTION
   .Ss Licensing
   Your manual must have a license.  It should be listed at the start of
   your document, just as in source code.
 .\" SECTION  .\" SECTION
 .Sh BEST PRACTICES  .Sh BEST PRACTICES
 The  The
Line 210  symbols and so on), use the escapes dictated in
Line 240  symbols and so on), use the escapes dictated in
 .Xr mdoc 7 .  .Xr mdoc 7 .
 .El  .El
 .\" SUBSECTION  .\" SUBSECTION
   .Ss Style
   The structure of the mdoc language makes it very hard to have any
   particular format style.  Keep your lines under 72 characters in length.
   If you must have long option lines, use
   .Sq \&Oo/Oc .
   .Em \&Do not
   use
   .Sq \&Xo/Xc ;
   instead, either fine another way to write long lines, or, at the
   absolute worst, use CPP-style newline escapes.
   .\" SUBSECTION
 .Ss References  .Ss References
 Other components may be referenced with the  Other components may be referenced with the
 .Sq \&Xr  .Sq \&Xr
Line 229  publications, please use the
Line 270  publications, please use the
 block macros.  block macros.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Formatting  .Ss Formatting
 Let the front-ends worry about formatting for you, but if you must think  .Em Don't style your manual.
 about formatting (at times necessary, especially for tagged and columnar  Give it meaningful content.  The front-end will worry about formatting
 lists), assume that your output device is a fixed-width terminal window:  and style.
 .Bd -literal -offset indent  
 \&.Bl \-tag \-width "-o outfile"  
 \&.It \&Fl \&Ar outfile  
 .Ed  
 .Pp  
 You may assume that the width calculated by the string literal  
 .Qq Fl o Ar outfile  
 will be covered by the \-width argument.  
 .\" SECTION  .\" SECTION
 .Sh MAINTENANCE  .Sh MAINTENANCE
 As your component changes and bugs are fixed, your manual may become out  As your component changes and bugs are fixed, your manual may become out
 of date.  You may be tempted to use automation tools like Doxygen to  of date.  You may be tempted to use automation tools like Doxygen to
 smooth the development of your manuals.  Don't.  Source documentation is  smooth the development of your manuals.  Don't.  Source documentation is
 different from a component manual.  different from a component manual.
Legend:
Removed from v.1.5  
changed lines
  Added in v.1.8
CVSweb