[GRASS-dev] Re: GRASS documentation

Mon Nov 5 09:37:52 EST 2007

Glynn Clements wrote on 11/05/2007 01:10 PM:
> Michael Barton wrote:
>   
>>> 1. They must not contain tags or entities which are not understood by
>>> the g.html2man script (tools/g.html2man/g.html2man).
>>>       
>> Can you or someone specify what these are?
>>     
>
> From a brief look at the g.html2man source, the following all appear
> to be understood to some extent:
>
> <A> <B> <BLINK> <BODY> <BR> <CODE> <DD> <DL> <DT> <EM> <H2> <H3> <H4>
> <HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P> <PRE> <SUP> <TABLE> <TD>
> <TH> <TITLE> <TR> <UL>
>
> However, g.html2man just uses regexp matching; it doesn't include a
> proper HTML parser. Consequently, there will be other restrictions on
> the precise format, e.g. I wouldn't expect line breaks between
> attributes to work.
>
>   
>>> 2. Any portions which are not modified must not be re-formatted during
>>> the editing process, as this will make the output from "cvs diff"
>>> useless.
>>>       
>> Maybe one way to do this is to work with a copy of the description.html
>> file, then use a simple text editor to cut out the edited/enhanced section
>> and paste it into the original--leaving other areas untouched.
>>
>> However, any significant changes, including adding images, could put a bunch
>> of stuff into a cvs diff.
>>     
>
> If there are many "genuine" changes, then you would expect to see a
> substantial diff. The point is that changes shouldn't result in excess
> diff output because unchanged sections have been reformatted (or
> rather, regenerated) by the editor.
>   

I have started a new file
SUBMITTING_DOCS
in the main source code directory. Hints should be collected there.

See also:
http://freegis.org/cgi-bin/viewcvs.cgi/grass6/SUBMITTING_DOCS?rev=HEAD&content-type=text/vnd.viewcvs-markup

Markus