[Mapserver-dev] Proposal for mapscript documentation using Re structuredtext

[Sean Gillies]

J.F.,

I don't think I made my proposal very clear.

Since SWIG doesn't, and won't in the foreseeable future according to
David Beazley, generate documentation from source, developers would
maintain the mapscript.txt file in RST format as the next best thing.

The DocBook stuff would be derived from mapscript.txt and documenters
would expand on it with usage examples and the @$%->{""} noise of
their favorite language. :)

Norman Vine's comments really made sense to me.  Developers need a
human readable plain text document.  In a perfect world, or a world
where we abandoned SWIG and wrote pure Perl/PHP/Python/Ruby mapscript
modules, we would just document the source well and that would do.
With SWIG, however, we seem to need an auxiliary document.

I am not saying that we ditch DocBook!  Only that for this particular
issue, it does not appear to me to be the way to go.

cheers,
Sean

On Feb 19, 2004, at 7:52 AM, Jean-Francois.Doyon at ccrs.nrcan.gc.ca wrote:

> Gents,
>
> First of all, I'd suggest this conversation be moved to the MDP's 
> list, or
> at least Kari be included ?
>
> Also, I just tried to document classes and methods and so on using 
> DocBook,
> and had only marginal success.  Turns out the stylesheet doesn't yet 
> support
> "Python" syntax ... Which is what I was tring to do.  It does support 
> Java
> and Perl though.
>
> I still feel however that we should stick to MDP set standards ... 
> that's
> why they're there.  The style sheet could maybe be extended to support 
> what
> we need it to ? The additions could even be fed back to maintainer of 
> the
> DocBook StyleSheets !
>
> All in all though, Kari is the documentation maintainer, and she really
> should be coordinating this effort, no ?
>
> And we have a mailing list for discussing documentation issues as 
> well, so
> might as well use it ?
>
> Just a thought :)
>
> J.F.
>
> -----Original Message-----
> From: mapserver-dev-admin at lists.gis.umn.edu
> [mailto:mapserver-dev-admin at lists.gis.umn.edu]On Behalf Of Steve Lime
> Sent: Thursday, February 19, 2004 1:36 AM
> To: dmorissette at dmsolutions.ca; sgillies at frii.com
> Cc: Mapserver-dev at lists.gis.umn.edu
> Subject: Re: [Mapserver-dev] Proposal for mapscript documentation using
> Restructuredtext
>
>
> I agree with Dan about merging documentation. If we don't want to go
> nuts and merge with PHP initially that's cool, but ultimately that
> should be the plan. That will help force keeping the variants in sync.
> Sean's example is fine as a starting point but I think we'll need a
> human(s) to keep the documentation on track an to  deal with language
> issues. Lowell Flak probably has the best version (aleit with frames)
> outside of the DMS PHP stuff now. Assuming he (and others) are
> interested, what about producing a base docbook version automagically
> and then turning them loose?
>
> Steve
>
>>>> Daniel Morissette <dmorissette at dmsolutions.ca> 02/18/04 10:54 PM >>>
> Sean Gillies wrote:
>>
>> Are you talking about merging the SWIG and PHP mapscript
> documentation?
>>  It might
>> be premature since the modules aren't truly merged yet.  There are
>> exclusive
>> functions in each and differently named functions and classes ... much
>
>> yet to do.
>>
>> I do think that new SWIG mapscript documentation will borrow heavily
> from
>> the PHP readme but should be documentation of the module as it
> currently
>> stands.
>>
>
> Yes, I was suggesting that we merge the SWIG and PHP docs. I realize
> that this merge of the docs may be a bit premature, but since I was the
> one who brought up the documentation issue in the first place I 
> couldn't
>
> really just sit back and keep PHP as a separate beast after advocating
> against having 4 or 6 separate sets of docs.
>
> Anyway, either way is good for me, as long as we have a mechanism for
> developers to maintain SWIG docs. :)  I'm willing to work with you (and
> the rest of the group) if you want to merge PHP docs with the SWIG docs
> now, but in order to facilitate things we may be better concentrating
> only on the SWIG stuff for now as you suggest, and merging with PHP 
> only
>
> down the road once the SWIG stuff is in good shape.
>
> Daniel
> -- 
> ------------------------------------------------------------
>   Daniel Morissette               dmorissette at dmsolutions.ca
>   DM Solutions Group              http://www.dmsolutions.ca/
> ------------------------------------------------------------
>
> _______________________________________________
> Mapserver-dev mailing list
> Mapserver-dev at lists.gis.umn.edu
> http://lists.gis.umn.edu/mailman/listinfo/mapserver-dev
>
> _______________________________________________
> Mapserver-dev mailing list
> Mapserver-dev at lists.gis.umn.edu
> http://lists.gis.umn.edu/mailman/listinfo/mapserver-dev
>