perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: modperl-docs/admin maintenance.pod README style.pod MAINTENANCE
Date Fri, 19 Apr 2002 17:33:09 GMT
stas        02/04/19 10:33:09

  Modified:    admin    README style.pod
  Added:       admin    maintenance.pod
  Removed:     admin    MAINTENANCE
  maintanance guidelines improved
  Submitted by:    Per Einar Ellefsen <>
  Revision  Changes    Path
  1.2       +7 -0      modperl-docs/admin/README
  Index: README
  RCS file: /home/cvs/modperl-docs/admin/README,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- README	15 Sep 2001 18:48:43 -0000	1.1
  +++ README	19 Apr 2002 17:33:09 -0000	1.2
  @@ -4,3 +4,10 @@
   style.pod       - please follow the guidelines in this doc when you
                     add new documentation.
  +                - A template for you to use for new documents.
  +                - Instructions on how to keep the site clean (check HTML
  +                  validity and links).
  1.6       +78 -12    modperl-docs/admin/style.pod
  Index: style.pod
  RCS file: /home/cvs/modperl-docs/admin/style.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- style.pod	3 Apr 2002 10:15:05 -0000	1.5
  +++ style.pod	19 Apr 2002 17:33:09 -0000	1.6
  @@ -1,4 +1,4 @@
  -=head1 mod_perl Documentation proeject's Style Guide
  +=head1 mod_perl Documentation project's Style Guide
   =head1 Introduction
  @@ -9,12 +9,15 @@
     % perldoc ./style.pod
  +Or convert it to HTML:
  +  % pod2html --infile=style.pod --outfile=style.html
   =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>
  +which then will be converted into HTML, PS, PDF and other formats. You
  +can learn the syntax of this format from the I<perlpod> manpage.
   =head1 Document structure
  @@ -33,8 +36,8 @@
     This is the title of the document
   There should be no POD escape characters in this section, since it can
  -be used in places where it's not possible to render things like I<> or
  +be used in places where it's not possible to render things like
  +IE<lt>E<gt> or BE<lt>E<gt>.
   This section won't appear in the finally rendered document
  @@ -88,14 +91,35 @@
     % perl -pi -e 's|\cM||' filename.pod
  +If you want to iterate over all files in a directory:
  +  % find . -type f -exec perl -pi -e 's|\cM||' {} \;
  +though watch for binaries, like images, which may get corrupted with
  +the above command. So something like more fine tuned command is
  +  % find . -type f -name "*.pod" -exec perl -pi -e 's|\cM||' {} \;
   =item *
  -Use CE<lt>ModuleE<gt> for module names, directives, etc.
  +Use CE<lt>ModuleE<gt> for module names, directives, function names,
  +etc. If correcting older documentation, remember not to leave any
  +quotes around the old names (for example, don't do CE<lt>"GET"E<gt>,
  +but just CE<lt>GETE<gt>).
  +Some older documentation uses BE<lt>E<gt> for module names. This was
  +because C<pod2man> didn't make CE<lt>E<gt> stand out enough. If you
  +spot any of these, please replace them with CE<lt>E<gt>. Use
  +BE<lt>E<gt> for stressing very important things. Use them
  +infrequently, since if there are many phrases in bold the original
  +intention is getting lost.
   =item *
   Use IE<lt>filenameE<gt> for filenames, URIs and things that are
  -generally written in italics
  +generally written in italics.
   =item *
  @@ -114,14 +138,31 @@
   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.
  +an easy C<s///> one liner.
   =item *
  -Linking between items in the same doc and across documents. Currently
  +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.
  +Currently, you can do this: for example, if editing the document
  +I<guide/performance.pod>, you can link to the I<install.pod> one by
  +  L<installation instructions|guide::install>
  +  L<installation instructions|docs::1.0::guide::install>
  +[the second example doesn't work yet, need to be fixed]
  +There are some other linking limitations; e.g. you can't link directly
  +to the I<index.html> of a section, and you can't link using relative
  +URIs. The latter limitation comes from the perlpodspec and hopefully
  +will be improved in the future.
   =item *
   Command line examples. Please use the following prompts to be
  @@ -145,11 +186,14 @@
  +Please try to avoid titles in B<ALLCAPS>. Use caps like B<This>, which
  +are a little more I<normal>.
   =item *
   Code examples:
  -META: not implemented yet! Currently use F<>
  +META: not implemented yet! Currently use FE<lt>E<gt>
   A new pod tag:
  @@ -157,7 +201,7 @@
  - <p><i>Example 1.1: This is a title</i></p> 
  + <p><i>Example 1.1: This is a title</i></p>
   =item *
  @@ -272,6 +316,28 @@
   (ending token), but it's a mess I think. I develop the text using
   I<cperl-mode.el> in xemacs which shows all space characters not
   followed by any text - this helps a lot!
  +=item *
  +Changes: In many directories, you will find a file named
  +I<Changes.pod>. This file contains the latest changes to a certain
  +documentation section, sorted by date (newest first). If you have made
  +any changes and sending a patch, it would be nice of you to include
  +the updated I<Changes.pod> file together with the patch.
  +A typical entry would look like this:
  +  =head1 Fri 19 Apr 18:37:00 CET 2002
  +  * Fixed some things and then other things, and then some other
  +    things bla bla bla. [John Doe E<lt>john.doe (at) aol.comE<gt>]
  +  * Other changes to I<file.pod>, and to I<otherfile.pod>. [stas]
  +Please try to keep things correctly aligned here (ie. the first
  +characters on each line should be vertically aligned with eachother),
  +as this file will most often be viewed as text.
  1.1                  modperl-docs/admin/maintenance.pod
  Index: maintenance.pod
  =head1 NAME
  Site Maintenance
  =head1 Description
  This document explains how to keep the site clean. 
  =head1 Validation Tasks
  We start from a site which is absolutely clean. Please keep it that
  =item *
  Validate internal and external links. For example use: the
  I<> from ( ) I usually
  run the check as:
    % --summary --recursive --broken --quiet \
      --html -D 10 http://localhost/modperl-site > report.html
  =item *
  Validate the correctness of the documents. The broken HTML can
  come from the broken source HTML document or bad templates. One of the
  tools that can be used is sgmlcheck. e.g.:
    % sgmlcheck dst_html/index.html
  META: anyone knows a better tool that can recursively check the whole
  site (ala and generate an nice report?

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message