[Dbix-class] Documentation formatting

[Justin Guenther]

On 3/24/06, Andrew Ford <A.Ford at ford-mason.co.uk> 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
> A.Ford at ford-mason.co.uk   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/
>