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

Diff for /mandoc/Attic/manuals.7 between version 1.15 and 1.16

version 1.15, 2009/06/25 10:55:40 version 1.16, 2009/07/16 22:16:44
Line 35  This document serves as a tutorial to writing 
Line 35  This document serves as a tutorial to writing 
 documentation  documentation
 .Pq Dq manuals .  .Pq Dq manuals .
 .\" SECTION  .\" SECTION
 .Sh COMPOSITION  .Sh ENVIRONMENT
 First, copy over the manual template from  First, copy over the manual template from
 .Pa /usr/share/misc/mdoc.template  .Pa /usr/share/misc/mdoc.template
 into your source directory.  into your source directory.
Line 103  for this document.  Rename the template file:
Line 103  for this document.  Rename the template file:
 .Pp  .Pp
 .Dl % mv mdoc.template myname.mysection  .Dl % mv mdoc.template myname.mysection
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Input Language  
 Manuals should  
 .Em always  
 be written in the  
 .Xr mdoc 7  
 formatting language.  
 .Pp  
 There exist other documentation-specific languages, such as the  
 historical  
 .Xr man 7  
 package of  
 .Xr roff 7 ;  
 newer languages such as DocBook or texinfo; or even ad-hoc conventions  
 such as README files.  
 .Em Avoid these formats .  
 .Pp  
 There are two canonical references for writing mdoc.  Read them.  
 .Pp  
 .\" LIST  
 .Bl -tag -width XXXXXXXXXXXXXXXX -offset indent -compact  
 .It Xr mdoc 7  
 formal language reference  
 .It Xr mdoc.samples 7  
 macro reference  
 .El  
 .Pp  
 Open the template you've copied into  
 .Pa myname.mysection  
 and begin editing.  
 .\" SUBSECTION  
 .Ss Development Tools  .Ss Development Tools
 While writing, make sure that your manual is correctly structured:  While writing, make sure that your manual is correctly structured:
 .Pp  .Pp
Line 184  Makefiles in order to automatically check your input:
Line 154  Makefiles in order to automatically check your input:
 Your manual must have a license.  It should be listed at the start of  Your manual must have a license.  It should be listed at the start of
 your document, just as in source code.  your document, just as in source code.
 .\" SECTION  .\" SECTION
 .Sh BEST PRACTICES  .Sh COMPOSITION
 The  Manuals should
   .Em always
   be written in the
 .Xr mdoc 7  .Xr mdoc 7
 and  formatting language.
 .Xr mdoc.samples 7  .\" PARAGRAPH
 files are indispensable in guiding composition.  In this section, we  .Pp
 introduce some  Open the template you've copied into
 .Ux  .Pa myname.mysection
 manual best practises:  and begin editing.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Language  .Ss Language
 .Bl -enum  .Bl -enum
Legend:
Removed from v.1.15  
changed lines
  Added in v.1.16
CVSweb