On 3/24/06, Andrew Ford <[EMAIL PROTECTED]> wrote: > A couple of general points on the documentation: > > 1. the indent for verbatim text is in many cases too small. For example > in the Manual/Example.pod file uses an indent of only one space. When > formatted through groff and printed out this results in a typeset indent > of less than 2mm, which is very hard to read. The spacing is also used > literally when man pages are displayed in Emacs. I would suggest a > standard indent in the POD of 4 spaces -- it also makes reading the raw > POD easier than indents of just one or two spaces.
The indent for verbatim text should be 2 spaces, I'll go around fixing it if it's not. I think 2 spaces is enough to be able to at a glance discern verbatim text from the descriptions. Comments? > 2. I would avoid the use of =head3 wherever possible as in pages printed > through groff these come out as lines set in italic at the sames size as > the body text (but visually actually lighter and more invisible than the > body text). Often one can reduce the number of levels by promoting the > =head2s to =head1s, so for example "=head2 Installation" in the > Example.pod becomes "=head1 Installation". Editorially there is no > reason why everything needs to go into the Description section (in > particular for the DBIx::Class::Manual::*.pod files), and the level 1 > headings stand out much more than the lower level headings. My commit yesterday got rid of every single occurrence of =head3 :) I do like the current system for header levels though, it seems very straightforward to me. =head1 for SYNOPSIS, DESCRIPTION etc., and =head2 for sub-headings. > 3. With regards the method signatures I prefer pseudo-code. It is what > most Perl modules use and visually it is easier to parse than a more > formal Arguments/Returns layout. Of course one could have both, e.g.: > > =item $rc = $obj->method($arg1, $arg2) > > =over 4 > > =item Arguments: > > =item Returns: > > =back Most functions have a synopsis given (in all cases I've seen it is given without an explicit heading) =head2 function =over 4 =item Arguments... =item Returns.... =back $schema->function($arg1, $arg2); Description Would it look better to have =item $schema->function(...) ? > > The problem is that headings like for example "source" (in the > DBIx::Class::Schema page) do not to my mind leap out as documentation of > the named method. I would prefer to see the formatted documentation for > a method looking something like this: > > $source = $schema->source($name) > Returns the result source for the registered name. > > > > BTW I had also thought about throwing together a quick reference card > for DBIx::Class for refcards.com. > > Regards > Andrew > > -- > Andrew Ford, Director Pauntley Prints / Ford & Mason Ltd > [EMAIL PROTECTED] South Wing Compton House > pauntley-prints.co.uk Compton Green, Redmarley Tel: +44 1531 829900 > ford-mason.co.uk Gloucester GL19 3JB Fax: +44 1531 829901 > refcards.com cronolog.org Great Britain Mobile: +44 7785 258278 > > > > _______________________________________________ > List: http://lists.rawmode.org/cgi-bin/mailman/listinfo/dbix-class > Wiki: http://dbix-class.shadowcatsystems.co.uk/ > IRC: irc.perl.org#dbix-class > SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/ > _______________________________________________ List: http://lists.rawmode.org/cgi-bin/mailman/listinfo/dbix-class Wiki: http://dbix-class.shadowcatsystems.co.uk/ IRC: irc.perl.org#dbix-class SVN: http://dev.catalyst.perl.org/repos/bast/trunk/DBIx-Class/
