stas 02/04/19 10:33:09
Modified: admin README style.pod
Added: admin maintenance.pod
Removed: admin MAINTENANCE
Log:
maintanance guidelines improved
Submitted by: Per Einar Ellefsen <[EMAIL PROTECTED]>
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.
+
+doc_template.pod
+ - A template for you to use for new documents.
+
+maintenance.pod
+ - 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>
-manpage.
+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
-B<>.
+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
+safer:
+
+ % 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
+using
+
+ L<installation instructions|guide::install>
+
+or
+
+ 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 @@
=head(1,2,3...)
+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 @@
becomes:
- <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.
+
=back
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
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
=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
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
