<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, May 27, 2013 at 12:18 AM, Stephen Woodbridge <span dir="ltr"><<a href="mailto:woodbri@swoodbridge.com" target="_blank">woodbri@swoodbridge.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi Daniel,<br>
<br>
You are doing an awesome job with the documentation. I have a few minor comments on things I have noticed while review it.<br>
<br>
* Can we break out the "Utility functions" to a separate page that gets indexed to make it easier to find. It is currently at the bottom of the pgrouting_analytics page.<br></blockquote><div><br></div><div style>
I didn't look at this much yet, but I thought there should be 1 page for each function.</div><div style>Then if these functions should be explained in context, grouped together however, then I would add a chapter to "Tutorials" for example.</div>
<div><br></div><div style>So if there is no single page yet for some functions, then it'S just not done yet.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
* pgr_quote_ident seems to be on its own page, but this and the utilities should be cross references may via the "See Also" links.<br></blockquote><div><br></div><div style>Some "See Also" links were obvious, but I thought it's OK to do this at the end. Otherwise if a page name changes, we need to fix it again. </div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
* I see references to "(built-in function)" but don't remember seeing any description of what this means to the user or why we are calling them out as such.<br></blockquote><div><br></div><div style>I don't remember either ;-)</div>
<div style>Where did you find this?</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
* many of the built-in functions do not conform to our naming convention. So may be we need to focus on updating these functions and the functions that call these. Also I think the doc is just out of date for many of these, because I seem to remember changing the names on these.<br>
</blockquote><div><br></div><div style>Could be. I'm usually looking at pgAdmin3 to get a list of all functions.</div><div style>Some I didn't touch, because I wasn't sure they would be removed or renamed.</div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
* I notice in the index that we have references "module", "[1]", "[2]", "[3]", etc. I'm not sure the [n] is very useful and should probably get changed to some text string that is more meaningful. And common module, ... in index makes no sense to me. I'm not sure how this all works in sphinx or if we can clean this up or not.<br>
</blockquote><div><br></div><div style>"Module" is a feature that is done by Sphinx auto-magically when it's not turned off. And a "Module" is defined like here</div><div style><br></div><div><font face="courier new, monospace">.. index::</font></div>
<div><font face="courier new, monospace"> single: pgr_kdijkstraCost(text,integer,integer[],boolean,boolean)</font></div><div><font face="courier new, monospace"> single: pgr_kdijkstraPath(text,integer,integer[],boolean,boolean)</font></div>
<div style><font face="courier new, monospace"> module: kdijkstra </font></div><div style><br></div><div style>I'm not su re really how useful this is for us. It just does the index records itself.</div><div style>
And I don't know well how to configure it. We can easily turn it off if it's just confusing and enable it again when we know out to use it right.</div><div style><br></div><div style>Daniel</div><div style><br></div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Anyway, some ideas to make things a little nicer. I really like how professional and consistent the docs look. Great job on these.<br>
<br>
Thanks,<br>
-Steve<br>
______________________________<u></u>_________________<br>
pgrouting-dev mailing list<br>
<a href="mailto:pgrouting-dev@lists.osgeo.org" target="_blank">pgrouting-dev@lists.osgeo.org</a><br>
<a href="http://lists.osgeo.org/mailman/listinfo/pgrouting-dev" target="_blank">http://lists.osgeo.org/<u></u>mailman/listinfo/pgrouting-dev</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><span style="font-family:arial,sans-serif;font-size:13px;border-collapse:collapse">Georepublic UG & Georepublic Japan<br>eMail: <a href="mailto:daniel.kastl@georepublic.de" style="color:rgb(66,99,171)" target="_blank">daniel.kastl@georepublic.de</a><br>
Web: <a href="http://georepublic.de/" style="color:rgb(66,99,171)" target="_blank">http://georepublic.de</a></span>
</div></div>