Re: questioning doc policy for @item

[Trevor Daniels]

Graham Percival Saturday, November 20, 2010 12:44 AM


> On Fri, Nov 19, 2010 at 08:55:26AM -0800, Mark Polesky wrote:
> > CG 4.3.6 says:
> > "Always put address@hidden on its own line, and separate
> > consecutive items with a blank line."
> >
> > In fact, we literally have thousands of cases:
> >
> > $ git grep -c "address@hidden" |
> >   sed -n 's/.*://p' |
> >   awk '{total+=$0}END{print total}'
> > 5103
>
> GDP only covered about 30% of the docs, and didn't strictly
> enforce the doc policy even within those areas, that's not a good
> reason to change the policy.

+1.  In the GDP'd parts of the NR there are only 7 exceptions.
(and in vocal none :)

> Ok, how about saying that you can have
>
> @itemize
> @item foo
> @item bar
> @end itemize
>
> as long as each item is less than a line.

I'm happy with this

> If there's multiple lines involved, then do the full
>
> @itemize
> @item foo
> far

No, I don't like this.  Too cluttered.

> or
>
> @itemize
> @item
> foo far

This is best, but I'd prefer a blank line before and after every 
@item
including the first one (IOW after @itemize as well) as long as this
looks OK in info.  That makes it easier to see the start and end of
the list when editing.

Trevor