[Dbix-class] Documentation formatting

[Andrew Ford]

Justin Guenther wrote:
> 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?
>
>   
I would still argue for 4 spaces.  Personally I find two an indent of 
two spaces difficult to make out in some circumstances -- don't know 
whether it is just my age or eyesight.  The Manual/Example.pod has 
extended code samples with just a one character indent, which is 
impossible to discern under Emacs or printed out.  The CPAN-style HTML 
formatting does of course make verbatim blocks very evident, but I for 
one tend to view man pages in an Xterm, under Emacs or printed through 
groff and badly formatted man pages are a right pain.

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