<div dir="ltr"><div><div><div>Hello Harrisou,<br><br></div>I guess the only reason was in fact to give some kind of numbering to the figures in html, and to reference them in the text.<br><br></div>Referencing in the text for html is not that important as figures are always placed in the correct place. For PDF it makes much more sense since images can be push to other pages and have their location changed. But the text used in the reference as nothing to do with the numbering in the figure, so it's kind of broken anyway.<br><br></div>AFAIK,Yves tried to upgrade sphinx and use numbering in html as well. If I remember well, the problem was to not do the numbering including all the documentation we end up with something like figure number 453...<br><div><div><br></div><div>Anyway, I suppor any effort to avoid this numbering system as maintaining this is an headache.<br><br></div><div>I will try do do some tests with numbering.<br><br></div><div>Alexandre Neto<br></div></div></div><br><div class="gmail_quote"><div dir="ltr">DelazJ <<a href="mailto:delazj@gmail.com">delazj@gmail.com</a>> escreveu no dia quinta, 20/10/2016 às 19:41:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr" class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg">Hi all,<br class="gmail_msg"><br class="gmail_msg"></div>Currently, most of the figures in QGIS doc are preceded by a kind of numbered title (ex: <strong class="gmail_msg">Figure Vector General 2)</strong> [1], meaning that when a new figure is added, the documenter should update the number of the following figures in the chapter. Not a really fulfilling task.<br class="gmail_msg"></div><div class="gmail_msg">In the .rst file, those "titles" are also preceded by a numbered reference (<b class="gmail_msg">_figure_vector_general_2</b> e.g., which follows the spelling of the title, unless it's the inverse. never mind).<br class="gmail_msg"><br class="gmail_msg"></div>So as discussed with Yves Jacolin and Alexander Neto (I can't recall when nor where), I began to fix these "titles" by replacing the number by a text related to the figure content, meaning that, for the example above, I'd have <b class="gmail_msg">_figure_vector_query builder</b> and <b class="gmail_msg">Figure Vector Query Builder</b>. This ensures unicity of reference and title and no need to update when new figure is inserted.<br class="gmail_msg"><br class="gmail_msg">BUT, i wonder if there is any real value/benefit in my fix, so would like to have your opinions and understand the reason of this design [2] :<br class="gmail_msg"><br class="gmail_msg"></div>- what is the real purpose of this title? It appears only in html (not in the pdf doc), the text is currently meaningless and with my proposal will simply be a kind of shortened duplicate of the real caption of the figure (present at the bottom of the figure). If it's about figure numbering then upgrading Sphinx and use the numfig variable  [3] in the configuration file would ensure to cover numbering of captions in both pdf and html.<br class="gmail_msg">So should we keep it?<br class="gmail_msg"><br class="gmail_msg"></div></div>- Is it mandatory to have a reference before every "title"?  As they follow the numbering system, the contributor must ensure to have updated all occurrences in the doc (if any) otherwise they lead to a wrong image (--> more work). Using a unique and not sequential naming would solve also this issue.<br class="gmail_msg"></div>But actually, few references are used in the doc to point the reader to a figure. And when they are, they make the pdf doc incomprehensible as they refer to a "title" that doesn't appear in the pdf doc [4].<br class="gmail_msg"><br class="gmail_msg"></div>So, my plan therefore is to:<br class="gmail_msg"><br class="gmail_msg"></div>- remove (instead of renaming) the "false" title at the top of the figure<br class="gmail_msg"></div>- remove (instead of renaming) the reference if it isn't used elsewhere. If used elsewhere, then it'll render the real caption of the figure in the text, for both html and pdf outputs. And if i'm not wrong, it'll also be possible to reference images from another chapter<br class="gmail_msg"></div>- and expect migration to a newer sphinx version to have all these changes cleaned for the next release.<br class="gmail_msg"><div class="gmail_msg"><br class="gmail_msg"></div><div class="gmail_msg">Any comments?<br class="gmail_msg"></div><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><br class="gmail_msg"></div><div class="gmail_msg">Greetings,<br class="gmail_msg"></div><div class="gmail_msg">Harrissou<br class="gmail_msg"></div><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg"><br class="gmail_msg"><div class="gmail_msg"><div class="gmail_msg">[1] <a href="http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html" class="gmail_msg" target="_blank">http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html</a><br class="gmail_msg">[2] <a href="http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure" class="gmail_msg" target="_blank">http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure</a><br class="gmail_msg">[3]  <a href="http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig" class="gmail_msg" target="_blank">http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig</a><br class="gmail_msg">[4] <a href="https://github.com/qgis/QGIS-Documentation/issues/788" class="gmail_msg" target="_blank">https://github.com/qgis/QGIS-Documentation/issues/788</a><br class="gmail_msg"></div></div></div></div></div></div></div></div></div></div></div>
_______________________________________________<br class="gmail_msg">
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..<br class="gmail_msg">
<a href="mailto:Qgis-community-team@lists.osgeo.org" class="gmail_msg" target="_blank">Qgis-community-team@lists.osgeo.org</a><br class="gmail_msg">
<a href="http://lists.osgeo.org/mailman/listinfo/qgis-community-team" rel="noreferrer" class="gmail_msg" target="_blank">http://lists.osgeo.org/mailman/listinfo/qgis-community-team</a></blockquote></div><div dir="ltr">-- <br></div><div data-smartmail="gmail_signature"><div dir="ltr"><div>Alexandre Neto</div><div>---------------------</div><div>@AlexNetoGeo</div><div><a href="http://sigsemgrilhetas.wordpress.com">http://sigsemgrilhetas.wordpress.com</a></div><a href="http://gisunchained.wordpress.com">http://gisunchained.wordpress.com</a><br></div></div>