perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: modperl-docs/admin README style.pod
Date Sat, 15 Sep 2001 18:48:43 GMT
stas        01/09/15 11:48:43

  Added:       admin    README style.pod
  preparing the guidelines for the future documentation contributors
  Revision  Changes    Path
  1.1                  modperl-docs/admin/README
  Index: README
  This directory includes various documents for the documentation writers
  and maintainers. The following is the explanation of the purpose of
  each file in this directory.
  style.pod       - please follow the guidelines in this doc when you
                    add new documentation.
  1.1                  modperl-docs/admin/style.pod
  Index: style.pod
  =head1 mod_perl Documentation proeject's Style Guide
  =head1 Introduction
  This document defines the style the authors should follow when writing
  a documentation for the mod_perl documentation project.
  To read this document in the proper way, run:
    % perldoc ./style.pod
  =head1 Formatting
  The documentation format is a plain POD (Plain Old Documentation),
  which then will be converted into HTML, XML, PS, PDF and other
  formats. You can learn the syntax of this format from the I<perlpod>
  =head1 Conventions
  Please try to use the following conventions when writing the docs:
  =item *
  Keep the text width < 74 cols.
  =item *
  Please avoid leaving ^M (CR on the DOS platforms). Either use the
  editor to remove these new line chars, or use Perl:
    % perl -pi -e 's|\cM||' filename.pod
  =item *
  Use CE<lt>ModuleE<gt> for module names, directives, etc.
  =item *
  Use IE<lt>filenameE<gt> for filenames, URIs and things that are
  generally written in italics
  =item *
  Use BE<lt>stressE<gt> for stressing things, but you should avoid using
  this tag unless you think things are very important. Over-use of the
  bold text reduces it's original intention -- make things stand out.
  =item *
  Use EE<lt>gtE<gt> for encoding C<$r-E<gt>filename> as in
  CE<lt>$r-EE<lt>gtE<gt>filenameE<gt>. Note that with some Perl versions
  C<pod2html(1)> and some other C<pod2*> are broken and don't correctly
  interpret this tag.
  =item *
  URLs are left unmarked. Pod2Html automatically identifies and
  highlights them. If later we would like to do that inline, we can have
  an easy s/// one liner.
  =item *
  Linking between items in the same doc and across documents. Currently
  use the technique explained in perlpod man page. It's not very
  sophisticated, but we will have to think about some better technique.
  =item *
  Command line examples. Please use the following prompts to be
  I<user> mode prompt:
    ai% ls -l
  I<root> mode prompt:
    ai# ls -l
  (ai for A.I., short and sweet)
  =item *
  Titles and subtitles:
  Use the head tags:
  =item *
  Code examples:
  A new pod tag:
    =example 1.1 This is a title
   <p><i>Example 1.1: This is a title</i></p> 
  =item *
  Figures (images):
  A new pod tag:
    =figure figure1.1.png This is a title
   <p><center><img src="figure1.1.png"></center></p>
   <p><center><b>Figure 1.1: This is a title</b></center></p>
  The index is extracted automatically from the file name.
  =item *
  Footnotes. These aren't defined in the current perlpod yet. So please
  use [F] footnote [/F] semantics and later we will come up with some
  way to make it a correct footnote.
  =item *
  Sidebars. Just like footnotes - it's not defined yet. Use [S] sidebar
  [/S] for now.
  =item *
  Try to keep the paragraphs not too long as it is hard to read them if
  they are too long. Follow common sense for that.
  Paragraphs are separated by an empty new line. Please make sure that
  you don't leave any spaces on this line. Otherwise the two paragraphs
  will be rendered as one. Especially remember to put a new empty line
  between text and code snippets.
  =item *
  Code snippets
  As you know in POD if you want something to be left untouched by the
  translator, you have to insert at least one space before each
  line. Please use the 2 space indent to specify the text snippet and
  for the code examples please use the 4 spaces indentation. No tabs
  Also remember that if the code snippet includes empty lines, you
  should prefix these with 2 spaces as well, so the examples will be
  continuous after they get converted into other formats.
  Here is an example:
    my $foo;
    for (1..10) {
         $foo += $_;
         if ($foo > 6) {
             print "foo\n";
         else {
             print "bar\n";
  From this example you can learn other style details that you should
  follow when writing docs.
  =item *
  Automatic code extraction
  The documentation includes numerous code snippets and complete
  scripts, you don't want the reader to type them in, so we want to make
  all the code available to the reader in a separated files, located in
  each chapter's parent's directory (e.g. ch2/
  Well at the beginning you might think that it might be a good idea to
  keep all the code in sync with the doc, but very soon you will find
  out that you change the code in the text and move the chapters and
  sections around, which makes it impossible to maintain the external
  source code.
  So what we have to do (and I haven't made it yet) is to use a
  convention for the code to be automatically extracted, e.g.:
    #!/usr/bin/perl -w
    use CGI;
    my $q = new CGI;
    print "Hi";
  So as I've said before we must not forget to add indentation to empty
  lines with no code in them, so that the parser picks up the whole
  code, removes the header with the filename and separator, puts back
  the code itself, saves it to the filename written at the top, and
  places it into the same directory name the text is located in. (Well
  it can be a separate tree for the code). If there are real empty
  lines, only part of the script will be saved, which will make the
  release broken. Another approach is to add some tail (ending token),
  but it's a mess I think. I develop the text using I<cperl-mode.el> in
  xemacs which shows all spaces not followed by any text - this helps a
  =head1 Review process
  If you want to send a review of a document to the document maintainer,
  please follow the following guidelines:
  =head2 Diff or not Diff?
  Since the text is changing a lot it's much harder to apply patches,
  especially if you happen to make a patch against an older version.
  Therefore we have found that it's much better for the docs maintainers
  to receive the whole document which is already corrected the way you
  think it should be and possible extra comments, as explained in the
  next section.
  Once we receive such a document we can use visual diff programs to
  make an easy merge, even if the document that you have modified has
  been changed since then. I suggest to use emacs's C<Ediff> module for
  visual merges. I'm sure other editors provide similar functionality.
  [Stas: if you know about these functionalities, please let me know so
  we can share the knowledge with others who don't use emacs.]
  =head2 Adding Inline Remarks
  =over 4
  =item *
  TODO semantics:
  I've gotten used to (META: do something) approach since the old days
  when I read the linux documentations. So you will see lots of META
  tags scattered around the sources. It makes it easy to see what things
  aren't yet complete and mark things that we want to work on later. So
  please use something like:
  [META: this should be completed]
  =item *
  Review Comments:
  If you review some document and you want to comment on something, just
  embed a paragraph with your comments enclosed in [] and with your name
  prepended. E.g:
  [Stas: This document needs a review.
  But it looks OK after all.]
  if your first name is a common one, please use the last name as well,
  or some other way to easily identify you so the maintainer of the
  document can contact you for an additional questions.
  =head1 Maintainers
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  Stas Bekman E<lt>stas@stason.orgE<gt>
  =head1 Authors
  Stas Bekman E<lt>stas@stason.orgE<gt>

View raw message