perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From perei...@apache.org
Subject cvs commit: modperl-docs/src/docs/general config.cfg cvs_howto.pod
Date Mon, 10 Jun 2002 21:35:27 GMT
pereinar    2002/06/10 14:35:27

  Modified:    src/contribute config.cfg maillist.pod share_code.pod
               src/docs/general config.cfg
  Added:       src/contribute cvs_howto.pod
               src/contribute/docs Changes_template.pod changes_file.pod
                        doc_template.pod maintenance.pod style.pod
  Removed:     src/docs/general cvs_howto.pod
  Log:
  Added many files to contribute, as well as links to other relevant information sources.
  Moved CVS Howto to contribute.
  Reviewed by:	stas
  
  Revision  Changes    Path
  1.4       +56 -3     modperl-docs/src/contribute/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/contribute/config.cfg,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- config.cfg	26 Apr 2002 15:32:23 -0000	1.3
  +++ config.cfg	10 Jun 2002 21:35:26 -0000	1.4
  @@ -6,12 +6,65 @@
   
         abstract => "How to contribute to the mod_perl community",
   
  -      chapters => [
  -          qw(
  +      group => 'Contribute at the Mailing List',
  +      chapters => [qw(
                maillist.pod
  +      )],
  +      
  +      group => 'Contribute to the Documentation',
  +      chapters => [qw(
                docs.pod
  +      )],
  +
  +      links => [
  +             {
  +              id => 'download_docs',
  +              link => '../download/docs.html',
  +              title => 'Download the Documentation',
  +              abstract => 'How to download the documentation to work on it locally'
  +             },
  +      ],
  +
  +      chapters => [qw(
  +             docs/style.pod
  +             docs/changes_file.pod
  +             docs/maintenance.pod
  +      )],
  +      links => [
  +             {
  +              id => 'doc_template',
  +              link => 'docs/doc_template.pod',
  +              title => 'Document Template',
  +              abstract => 'When creating new documents, use this template.'
  +             },
  +             {
  +              id => 'changes_template',
  +              link => 'docs/Changes_template.pod',
  +              title => 'Changes Template',
  +              abstract => 'Example document for the Changes file'
  +             },
  +      ],
  +
  +      group => 'Contribute by Sharing Code',
  +      chapters => [qw(
                share_code.pod
  -            )
  +             cvs_howto.pod
  +      )],
  +      links => [
  +             {
  +              id => 'devel-guide',
  +              link => '../docs/2.0/devel/index.html',
  +              title => "mod_perl 2.0 Developer's guide",
  +              abstract => 'If you want to contribute, you should read
  +                          this documentation to learn mod_perl 2 coding'
  +             },
         ],
  +      
  +      copy_glob => [qw(
  +             docs/doc_template.pod
  +             docs/Changes_template.pod
  +      )],
   
   );
  +
  +1;
  
  
  
  1.5       +21 -3     modperl-docs/src/contribute/maillist.pod
  
  Index: maillist.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/contribute/maillist.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- maillist.pod	5 Jun 2002 07:34:46 -0000	1.4
  +++ maillist.pod	10 Jun 2002 21:35:26 -0000	1.5
  @@ -17,7 +17,9 @@
   
   You don't have to be a guru to be a very valuable person to the
   mod_perl community. Through answering questions you learn a lot by
  -yourself and eventually become a guru yourself.
  +yourself and eventually become a guru too. Actually, by doing a little
  +research for people (which they should have been doing themselves),
  +you'll learn of things you had never even thought of!
   
   =head1 Helping Navigating the Documentation
   
  @@ -26,8 +28,24 @@
   well indexed, it can be hard to find the right piece of information,
   especially for a novice mod_perl user. If you point someone to the
   existing documentation, please try to point her to the specific URL
  -containing the information, and not just to "the mod_perl guide" in
  -general.
  +containing the information, and not just to "the mod_perl
  +documentation" in general.
  +
  +=head1 Pointing to Past Discussions
  +
  +Very often there will come up questions that have been answered
  +before. Instead of replicating answers, do everyone a favor and
  +retrieve the URL of the discussion from the
  +L<archives|maillist::modperl/"Searchable_Archives">, replying with
  +that if it answers the question or at least helps along the way.
  +
  +=head1 Obeying the Email Etiquette
  +
  +Do not forget the important L<mailing list
  +guidelines|maillist::email-etiquette>. Whenever posting to the list,
  +you should be aware of these and follow them as best as
  +possible. Furthermore, if some users seem to not be aware of it, don't
  +hesitate about pointing them to that place.
   
   =cut
   
  
  
  
  1.5       +1 -1      modperl-docs/src/contribute/share_code.pod
  
  Index: share_code.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/contribute/share_code.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- share_code.pod	12 May 2002 05:41:20 -0000	1.4
  +++ share_code.pod	10 Jun 2002 21:35:26 -0000	1.5
  @@ -31,7 +31,7 @@
   Before submitting a new C<Apache::> module to CPAN, please discuss it
   first on the L<mod_perl list|maillist::modperl>. It's important
   to choose a good intuitive name for your module. Also it's possible
  -that a module with a similar functionality already exists and most
  +that a module with similar functionality already exists and most
   likely that someone will point it out. In which case you may want to
   help developing this existing module instead and integrating your
   features into it.
  
  
  
  1.1                  modperl-docs/src/contribute/cvs_howto.pod
  
  Index: cvs_howto.pod
  ===================================================================
  =head1 NAME
  
  CVS Howto
  
  =head1 Description
  
  A short description how to use CVS to access the mod_perl and related
  projects source distributions (also applies to the documentation
  project).
  
  Just as cvs access to the Apache development tree, the mod_perl code
  pulled from cvs is not guaranteed to do anything, especially not
  compile or work.  But, that's exactly why we are using cvs, so
  everyone has access the latest version and can help see to it that
  mod_perl does compile and work on all platforms, with the various
  versions and configurations of Perl and Apache.  Patches are always
  welcome and simply testing the latest snapshots is just as, if not
  more helpful.
  
  It's recommended to subscribe to the L<modperl-cvs|maillist::cvs>
  list, which is the place cvs commit logs and diffs are mailed to; at
  least if you're going to work on the code.
  
  =head1 Anonymous CVS
  
  You can get cvs here: http://www.cvshome.org/
  
  =head2 Checking Out
  
  To checkout a fresh copy run the following commands from the directory
  you want the sources to stay in:
  
    % cvs -d ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" login
  
  (use the password "anoncvs")
  
    % cvs -d ":pserver:anoncvs@cvs.apache.org:/home/cvspublic" co modperl
  
  After cvs has finished downloading the files you will find a new
  directory called I<modperl> in the current working directory.
  
  =head2 keeping your copy up to date
  
  To keep your local copy in sync with the repository, do
  
    % cvs update -dP
  
  in the top directory of the project. You should run update evertime
  before you start working on the project.
  
  =head2 Sending Patches
  
  To send a patch, first run:
  
    % cvs diff -u
  
  in the top directory of the project. The output of diff will be sent
  to STDOUT, so it might be better to redirect the output to a file:
  
    % cvs diff -u > patch
  
  If you added files or directories to the project, do a diff against
  I</dev/null>:
  
    % diff -u /dev/null newdir/newfilename
  
  When this patch is applied, the new dir and the new file will be
  automatically created.
  
  On Windows-based systems, you can do
  
    % diff -u NUL newdir/newfilename
  
  instead.
  
  Then send your patch to the maintainer of the project, or the
  appropriate mailing list.
  
  =head2 Useful Default Parameters
  
  Here are some recommended parameters. Save them in I<~/.cvsrc>, so
  you don't have to type them everytime you use cvs.
  
    cvs -z9
    update -dP
    diff -u
  
  =over
  
  =item *
  
  I<cvs -z9> sets the compression level to 9 (the highest value) to
  speed up downloading.
  
  =item *
  
  I<update -d> automatically creates directories that are missing in
  your local copy because they where added to the repository after your
  initial checkout or your last update.
  
  =item *
  
  I<update -P> automatically deletes empty directories.
  
  =item *
  
  I<diff -u> to use the unified output format so that your changes can
  be easily merged back into the repository.
  
  =back
  
  =head1 cvsup
  
  C<cvsup> has come out of the FreeBSD group. It's a client/server beast
  that offers an efficient way to sync collections of files over the
  net, and it is very CVS aware, allowing synchronisation of
  repositories or checked out files using the cvs deltas to bring the
  client side files up to date with minimal data transfer.
  
  For a FreeBSD cvsup client see
  http://www.freebsd.org/cgi/ports.cgi?query=cvsup&stype=all
  
  Others (SunOS, alpha.osf, linux, Solaris2.4, HPAA 10.2, irix):
  ftp://ftp.postgresql.org/pub/CVSup/
  
  Here's a config file for the client (cvsup) to sync modperl sources.
  
    *default tag=.
    # comment out the above if you want the raw cvs files
    
    *default host=cvs.apache.org
    *default prefix=/path/on/this/machine/to/install/
    # a subdir for modperl will appear here ^^^
    
    *default base=/path/on/this/machine/where/cvsup/will/keep/status/info
    # you'll never need to look in the 'base' dir.
    
    *default release=cvs delete use-rel-suffix compress
    
    modperl
    #apache-1.3
    #apache-docs
    #modperl-2.0
    #httpd-2.0
    #modperl-docs
    #make your picks above by uncommenting the entries
  
  
  =head1 Getting CVS snapshots
  
  In case you can't get anonymous CVS access to work (or don't want to),
  there is another possibility: at http://cvs.apache.org/snapshots/ ,
  there are snapshots of the interesting CVS repositories you might
  want to download. These snapshots are extracted from CVS every 6
  hours, so might not contain the I<latest> changes, but you'll get
  pretty close. The file names contain the date and time, which you can
  also see in the directory listing. So just grab the latest one by
  date, which will get you the latest version.
  
  See the list of interesting repositories
  L<below|/"mod_perl_and_Related_Projects_on_cvs_apache_org"> to find
  out which snapshots you might want to download.
  
  =head1 Inspecting the CVS server with ViewCVS
  
  ViewCVS is installed on the Apache CVS server. You can reach it at
  http://cvs.apache.org/viewcvs.cgi/.
  
  From there you can browse the list of available projects, look at the
  files contained in those projects, their logs, and do colored diffs
  between versions. This is information you can get from your CVS client
  (through C<cvs log>, C<cvs diff> and friends), but the web interface
  makes it much easier to get a good overview of the different files.
  
  =head1 CVS+SSH access for mod_perl committers
  
  mod_perl committers need to use CVS over SSH. Normal SSH
  authentications mechanisms apply; you can use public key, password,
  etc. Refer to your ssh client's manpage.
  
  =head2 Getting the Client
  
  If you don't have SSH already installed, you can get it from
  I<http://www.openssh.org/>. If your platform is not supported, this
  site provides pointers to other implementations. For example for
  Windows, you might want to look at C<Putty>,
  http://www.chiark.greenend.org.uk/~sgtatham/putty/, especially the
  C<plink> client which runs from the command line. Also see
  C<http://www.ssh.com/>.
  
  =head2 Setting Up the Environment
  
  Set your C<CVS_RSH> environment variable to C<ssh> (if your SSH
  program has a different name, such as I<plink>, use that instead). For
  example if you are using Bourne-style shell:
  
    % export CVS_RSH=ssh
  
  You should add this your I<.bashrc> or similar file, so that it's set
  on startup. For Windows, add the line
  
    set CVS_RSH=ssh
  
  to I<autoexec.bat>, or set the environment variable through the System
  section of the I<Control Panel> on NT systems.
  
  The CVS Root is different when using SSH. It's:
  
    username@cvs.apache.org:/home/cvs
  
  where I<username> is your username on the I<cvs.apache.org> machine.
  
  =head2 Working with CVS
  
  For example let's say you want to work with the I<modperl-docs> cvs
  repository.
  
  To check out the repository do:
  
    % cvs -d username@cvs.apache.org:/home/cvs checkout modperl-docs
  
  or the shortcut:
  
    % cvs -d username@cvs.apache.org:/home/cvs co modperl-docs
  
  If it's a first time you ssh to cvs.apache.org, it will ask if you
  want to allow the host I<cvs.apache.org>. Answer I<yes>. Then you are
  asked for your password; type it in. Now you will get a freshly
  checked out copy of the I<modperl-docs> repository.
  
  If you get permission problems, most likely your Unix group wasn't
  adjusted. Contact the person who gave you the cvs access.
  
  To bring your repository's copy up to date, run:
  
    % cvs update -dP
  
  or the shortcut:
  
    % cvs up -dP
  
  The C<-d> option builds directories (if any were added since last
  update), like checkout does. The C<-P> option prunes empty directories
  if any. You can put these and other handy options into the rc
  file. For example with C<openssh> and C<ssh> clients, this is
  I<~/.cvsrc>. Usually we have the following in this file.
  
    cvs -z9
    update -dP
    diff -u
  
  The first line tells to use the best compression level when
  communicating with the server. The last line will do a unified I<diff>
  when C<cvs diff> is used.
  
  If you have done some changes, which weren't committed, it's possible
  that while trying to merge the differences the client will report
  about collisions which happens when you've happened to change
  something that was changed and committed by somebody else. You will
  have to resolve the conflicts by manual editing of the files in
  question.
  
  Normally, most changes should go through peer review first. It might
  be a good idea to discuss the intricacies of a change on the
  appropriate mailing list before committing anything. Then, to commit:
  
    % cvs commit filename(s)
  
  or the shortcut:
  
    % cvs ci filename(s)
  
  But first run C<cvs update> to avoid any problems with out of date
  versions of files. If you get any conflicts because of it, these must
  be changed before doing C<cvs commit>, which will incorporate any
  changes into the repository. To commit only a single file, do:
  
    % cvs commit path/to/file
  
  If a file or a directory is not under cvs control you have to add it
  to the cvs first and then commit it:
  
    % cvs add path/to/file
    % cvs ci path/to/file
  
  Usually cvs recognizes binary files by their extensions (e.g. images),
  but if you commit a file with some unusual extension tell your cvs
  client that it's a binary file with C<-kb> option:
  
    % cvs add -kb path/to/binary/file
  
  Then, to add it permanently, you will have to commit it.
  
  =head2 A Special Note to modperl-docs Committers
  
  One B<very> important note before (ab)using your powers: the mod_perl
  documentation project makes use of an automatic build system. This
  means that any changes committed will be periodically rebuilt to create
  the new site (so you don't have to login and do the manual
  update/rebuild). This is great, but a side-effect of this is that if
  someone commits anything that doesn't work, the build will fail, and
  might break parts of the site.
  
  To avoid these problems, please make sure to run C<bin/build> on your
  working copy to test I<before> committing. Also, make sure to run C<cvs
  update> to check that you have added all files to the repository; it's 
  easy to forget adding the files you have created, and C<bin/build>
  will work fine your side, but will fail for others because of the
  missing files the build depends on.
  
  =head2 Avoiding Typing in the Password
  
  After awhile you will get tired of typing the password for every cvs
  operation that you do. You can avoid that using the public key
  authentication and the ssh authentication agent. Refer to your ssh
  client's manpage for more information. For example for the C<openssh>
  and C<ssh> clients, the C<ssh-add> utility can be used to enter the
  password once for your private key and then it'll do the public key
  authentication for you every time you work with cvs over ssh (as long
  as C<ssh-agent> is running). Refer to the relevant manpage for more
  info (I<ssh-agent> in this case).
  
  
  =head1 mod_perl and Related Projects on cvs.apache.org
  
  =over
  
  =item modperl
  
  sources for mod_perl 1.x, for use with apache-1.3
  
  =item apache-1.3
  
  the Apache 1.3 HTTP Server
  
  =item modperl-2.0
  
  the new version of mod_perl, for use with httpd-2.0. See the L<install
  docs|docs::2.0::user::install::install> for more information about
  downloading the 2.0 components and installing them.
  
  =item httpd-2.0
  
  the new Apache 2.0 HTTP Server
  
  =item apr
  
  needed for modperl-2.0
  
  =item apr-util
  
  needed for modperl-2.0
  
  =item modperl-docs
  
  the mod_perl documentation (i.e. this site). See the L<documentation
  download|download::docs> for information on how to download, build and
  submit patches to the documentation.
  
  =back
  
  Or see http://cvs.apache.org/viewcvs.cgi/ for a list of all projects.
  
  =head1 See also
  
  =over
  
  =item * 
  
  http://httpd.apache.org/dev/anoncvs.txt
  
  For a basic introduction to Anonymous CVS on the Apache CVS server.
  
  =item * 
  
  http://cvsbook.red-bean.com/
  
  Open Source Development with CVS is a book published by Coriolis Inc.
  as part of the Coriolis OpenPress series. Chapters 2, 4, 6, 8, 9, and
  10 -- comprising a complete introduction, tutorial and reference to
  CVS -- are being released free under the terms of the GNU General
  Public License.
  
  =item * 
  
  http://www.cvshome.org/docs/manual/
  
  Version Management with CVS by Per Cederqvist et al is the "official"
  manual for CVS.  Commonly known as "the Cederqvist," the manual covers
  repositories, branches, and file maintenance, and includes reference
  material for both CVS users and CVS repository administrators.
  
  =back
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  =over
  
  =item *
  
  the L<documentation mailing list|maillist::docs-dev>
  
  =back
  
  
  =head1 Authors
  
  =over
  
  =item *
  
  Thomas Klausner E<lt>domm (at) zsi.atE<gt>
  
  =item *
  
  Doug MacEachern
  
  =item *
  
  Per Einar Ellefsen E<lt>per.einar (at) skynet.beE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  =cut
  
  
  
  1.1                  modperl-docs/src/contribute/docs/Changes_template.pod
  
  Index: Changes_template.pod
  ===================================================================
  =head1 NAME
  
  Changes
  
  =head1 Description
  
  Refer to this document to learn what changes were made to the
  documents since you read them last time. 
  
  The most recent changes are listed first.
  
  =head1 ??? (format: Sat Nov 12 20:34:23 CET 2002)
  
  * ... [...]
  
  * ... [...]
  
  
  =cut
  
  
  
  
  
  
  
  
  
  
  
  
  1.1                  modperl-docs/src/contribute/docs/changes_file.pod
  
  Index: changes_file.pod
  ===================================================================
  =head1 NAME
  
  Changes File Specs
  
  =head1 Description
  
  This doc clears the confusion regarding the need and the maintenance
  guidelines of I<Changes.pod> files in the project.
  
  =head1 Who Has Contributed What And When
  
  All the modifications of every single file can be viewed via C<cvs
  log> command. e.g., to check the history of this very file, one would
  run:
  
    % cvs log src/contribute/docs/changes_file.pod
  
  Which will display all the commit logs, who has committed the change,
  who has submitted the changes, etc.
  
  =head1 The Art of Changes File
  
  The I<Changes.pod> document is not the same as the history of all
  changes. This document is for end user consumption, who is interested
  to know what are the major changes since the last time she read the
  documents. Or minor but important changes, like bug fixes.
  
  Therefore the I<Changes.pod> document is only needed when some
  sub-project goes through changes which will be of interest to the
  reader. Don't just add I<Changes.pod> everywhere, until you really
  think it's needed.
  
  The format of this document should be as dense as possible, so the
  reader can read through it fast and pin-point if there is something
  interesting to it.
  
  There is no need to log the date every time the change is done ('cvs
  log' has all the info). Though it's nice to group the changes by
  certain milestones, so let's say every few month a time stamp is added
  in front of the group of the changes since the last timestamp and new
  changes will go to the new group. The change entries in the
  I<docs/1.0/guide/Changes.pod> is a good example of that. In addition
  it used to add a version number for each milestone, which is very
  optional now.
  
  This file should have the latest changes on the top.
  
  =head1 The Scope of Changes.pod
  
  Usually we have a separate I<Changes.pod> file for each sub-set of the
  documents. If you feel that the changes for a few sub-sets nested in
  the same super-set of docs can be maintained in one file, have only
  one I<Changes.pod>. Later if this file becomes too overloaded and its
  added value is getting diminished, split it into a few I<Changes.pod>
  files placed in each sub-set. Or if you think that this will happen in
  the near future do this from the beginning to avoid the slicing work
  later.
  
  =head1 Adding Credits
  
  If you are the maintainer of the document, you don't have to credit
  each change done by you, with your name, simply leave the change entry
  un-credited, which automatically implies that you did that.
  
  If someone commits something to the document maintained by someone
  else simply mark it with your name e.g. [Thomas Klausner]. Those who
  commit all the time, should pick some short (nick?)name that will
  distinguish them from others and make their changes with it. e.g
  [thomas]. The idea is to have the changes file with as little noise as
  possible.
  
  There is a special case where we want to credit people who contributed
  very minor fixes, which don't deserve a separate changes entry. In
  this case just have a special entry like C<Minor fixes>, where you
  simply list the names of those who contributed because we want to give
  credits to everybody. Again the I<docs/1.0/guide/Changes.pod> file
  perfectly demonstrates that.
  
  =head1 Sample Changes.pod
  
  See I<docs/1.0/guide/Changes.pod> as a good example.
  
  A typical entry looks like this:
  
    =head1 ???
    
    * books: 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>]
    
    * file: Added some content. [stas]
    
    * otherfile: updated the "Maintenance" section, adding references to
      bla bla bla [other person]
  
    =head1 Sat Nov 12 22:05:23 CET 2002
  
    * docs::index : moved tutorials to "Other documentation" [stas]
    
    * performance: minor corrections [thomas]
  
  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.
  
  As you can see, we try to collect a number of changes, then timestamp
  the document like a "version".
  
  You can use the I<Changes_template.pod> as a starting point.
  
  =cut
  
  
  
  1.1                  modperl-docs/src/contribute/docs/doc_template.pod
  
  Index: doc_template.pod
  ===================================================================
  =head1 NAME
  
  TITLE goes here
  
  =head1 Description
  
  the first paragraph of the description will be displayed on the index
  page, so make sure to put the general overview in this first paragraph.
  
  =head1 ...
  
  =head2 ...
  
  =head1 Maintainers
  
  The maintainer is the person you should contact with updates,
  corrections and patches.
  
  =over
  
  =item * Foo Bar E<lt>foo (at) bar.example.comE<gt>
  
  =back
  
  =head1 Authors
  
  =over
  
  =item * Foo Bar E<lt>foo (at) bar.example.comE<gt>
  
  =item * Foo Tar E<lt>foo (at) tar.example.comE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  =cut
  
  
  
  
  1.1                  modperl-docs/src/contribute/docs/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
  way.
  
  =over
  
  =item *
  
  Validate internal and external links. For example use: the
  I<checklink.pl> from ( http://validator.w3.org/checklink ) I usually
  run the check as:
  
    % checklink.pl --summary --recursive --broken --quiet \
      --html -D 10 http://localhost/modperl-site > report.html
  
  Internal links validation also applies to POD documents. It's easy to
  do this, just rebuild the site with the C<-l> argument to
  C<bin/build>:
  
    % bin/build -lf
  
  =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 checklink.pl) and generate an nice report?
  
  =back
  
  =cut
  
  
  
  1.1                  modperl-docs/src/contribute/docs/style.pod
  
  Index: style.pod
  ===================================================================
  =head1 NAME
  
  Documentation Style Guide
  
  =head1 Description
  
  This document defines the style the authors should follow when writing
  a documentation for the mod_perl documentation project.
  
  =head1 Formatting
  
  The documentation format is plain POD (Plain Old Documentation), 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 and the
  new I<perlpodspec> manpage from 5.8 versions of Perl.
  
  =head1 Document structure
  
  The document should be constructed from at least the following
  C<=head1> sections.
  
  =over
  
  =item NAME
  
  The first section's title must be C<NAME> with a short title as a
  content. e.g.:
  
    =head1 NAME
    
    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
  IE<lt>E<gt> or BE<lt>E<gt>.
  
  This section won't appear in the finally rendered document, except as
  the title of the document.
  
  =item DESCRIPTION
  
  C<DESCRIPTION> or C<Description>, so it gets rendered like other =head
  sections in the document in case you don't use upper case for these.
  
  The first paragraph of this section will be used on the index pages
  that link the documents together. e.g.:
  
    =head1 Description
    
    This document explains...
  
  This section must appear in the first three sections of the
  document. It's not required to be the one following the C<NAME>
  section since in Perl modules pods it usually comes third after the
  C<SYNOPSIS> section.
  
  =item Author
  
  The author of the document with an optional email address or other
  means for reaching the author.
  
  Usually comes as one of the last sections of the document.
  
  =back
  
  =head1 Conventions
  
  Please try to use the following conventions when writing the docs:
  
  =over
  
  =item *
  
  When using domain names in examples use only I<example.com> and its
  derivatives (e.g. I<foo.example.com>) or I<localhost> (or
  I<localhost.localdomain>). I<example.com> is an official example
  domain.
  
  =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
  
  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 or the I<cache.*.dat> files
  left by DocSet, which may get corrupted with the above command. So
  something like this more fine tuned command is safer:
  
    % find . -type f -name "*.pod" -exec perl -pi -e 's|\cM||' {} \;
  
  
  =item *
  
  Use C<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.
  
  =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 C<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.
  
  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
  using
  
    L<installation instructions|guide::install>
  
  or
  
    L<installation instructions|docs::1.0::guide::install>
  
  You may also link to the index of a section by using
  
    L<The Guide|guide::index>
  
  As you can see in the base I<config.cfg> file, there are some search
  paths used to make linking more comfortable. That is why you can, for
  some documents, use absolute links ( la C<docs::1.0::guide::install>)
  and relative links (C<guide::install>).
  
  =item *
  
  Command line examples. Please use the following prompts to be
  consistent.
  
  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:
  
    =head(1,2,3...)
  
  Please try to avoid titles in B<ALLCAPS>. Use caps like B<This>, which
  are a little more I<normal>. If porting old documents, correct this.
  
  =item *
  
  Code examples:
  
  META: not implemented yet! Currently use FE<lt>E<gt>
  
  A new pod tag:
  
    =example 1.1 This is a title
  
  becomes:
  
   <p><i>Example 1.1: This is a title</i></p>
  
  =item *
  
  Figures (images):
  
  META: not implemented yet! Currently use =for html
  
  A new pod tag:
  
    =figure figure1.1.png This is a title
  
  becomes:
  
   <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 *
  
  META: not implemented yet!
  
  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 *
  
  META: not implemented yet!
  
  Sidebars. Just like footnotes - it's not defined yet. Use [S] sidebar
  [/S] for now.
  
  =item *
  
  Paragraphs.
  
  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
  please.
  
  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. In any case, follow the mod_perl coding
  guidelines for code.
  
  =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/ex2.pl)
  
  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.:
  
    file:example.pl
    ----------------
    #!/usr/bin/perl -w
    
    use CGI;
    my $q = new CGI;
    
    print "Hi";
  
  So as I've said before we must not forget to add 2 space characters
  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 space characters not
  followed by any text - this helps a lot!
  
  =item * Documenting Important Changes
  
  If you are posting a patch or a committing a patch, please document
  the important changes that would be of interest to the end user. For
  more info please read the I<changes_file.pod> doc.
  
  =back
  
  =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.]
  
  To submit normal patches (when they are minor changes, and you're sure
  the document hasn't changed), use the C<cvs diff> method:
  
    % cvs diff -u src/docs/1.0/...pod
  
  If you're adding a file, especially if it needs a new directory, it
  might be a good idea to submit a patch against C</dev/null>, which
  will automatically create the new directory, like this.
  
    % diff -u /dev/null newdir/newfilename.pod
  
  Or on Windows:
  
    % diff -u NUL newdir/newfilename.pod
  
  =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.
  
  =back
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  Stas Bekman E<lt>stas (at) stason.orgE<gt>
  
  =head1 Authors
  
  =over 
  
  =item * Stas Bekman E<lt>stas (at) stason.orgE<gt>
  
  =back
  
  =cut
  
  
  
  1.5       +0 -1      modperl-docs/src/docs/general/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/general/config.cfg,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- config.cfg	29 May 2002 05:03:41 -0000	1.4
  +++ config.cfg	10 Jun 2002 21:35:27 -0000	1.5
  @@ -36,7 +36,6 @@
   
       group => 'Miscellaneous',
       chapters => [qw(
  -        cvs_howto.pod
           Changes.pod
       )],
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message