[mapserver-dev] Documentation Updates

[Howard Butler]

On Nov 24, 2008, at 4:13 PM, Tamas Szekeres wrote:

> Howard,
>
> It looks really cool!
> Just looking into the docs I'm not sure how the docs should properly  
> reference to each other.

Sphinx builds a giant dictionary when it makes the first pass through  
the documents.  It stuffs references to all headings and explicitly  
defined references into this dictionary, and then you can use the  
Sphinx ReST extension :ref: to refer to these anchors.  You want to  
keep them somewhat specific because you want them to act as global  
(within the context of the documentation) identifiers.  For example,  
we have :ref:`mapfile` which points to the main mapfile reference,  
or :ref:`LAYER` which points to the layer reference.


> It seems we should alter the previous approach in the documents,  
> like for http://iowa.hobu.biz/msdocs/build/html/references/mapscript/dotnet_compile.html 
>  to avoid the warning.

That warning is because the win32 compilation doc hasn't been turned  
into ReStructured text yet.

>
> Should we continue keep the doc along with the code in different  
> directories or you're planning to set up a central repository  
> somewhere?
> In my case the C# readme is the same as the compile doc exposed to  
> the web site, so it would be reasonable to keep this doc in place.
>

I was deliberately pursuing a strategy of pulling docs *out* of the  
places they were maintained in the source tree and into the  
documentation tree. For example, I moved the main SWIG MapScript doc  
to http://trac.osgeo.org/mapserver/browser/trunk/docs/references/mapscript/mapscript.txt 
   Things might continue to move around a bit more as we reorganize.   
I moved the dotnet_compile doc out of mapscript/doc as well and into  
the docs/references/mapscript directory.


> Best regards,
>
> Tamas
>
>
>  PS: I'd apply for removing the trailing 't' char in my surname in  
> the docs. My nickname (szekerest) contains just the abbreviation of  
> 'tamas' in the end :-D  This is because the Hungarians use reverse  
> name ordering (surname firstname) by default, causing various kind  
> of unexpected problems for us in various places ;-)

I suck.  Please make any fixes to the docs as necessary :)