[Qgis-community-team] Issues with figure numerotation cleanup

[Alexandre Neto]

Hello Harrisou,

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.

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.

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...

Anyway, I suppor any effort to avoid this numbering system as maintaining
this is an headache.

I will try do do some tests with numbering.

Alexandre Neto

DelazJ <delazj at gmail.com> escreveu no dia quinta, 20/10/2016 às 19:41:

> Hi all,
>
> Currently, most of the figures in QGIS doc are preceded by a kind of
> numbered title (ex: *Figure Vector General 2)* [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.
> In the .rst file, those "titles" are also preceded by a numbered reference
> (*_figure_vector_general_2* e.g., which follows the spelling of the
> title, unless it's the inverse. never mind).
>
> 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 *_figure_vector_query builder* and *Figure Vector Query Builder*.
> This ensures unicity of reference and title and no need to update when new
> figure is inserted.
>
> 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] :
>
> - 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.
> So should we keep it?
>
> - 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.
> 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].
>
> So, my plan therefore is to:
>
> - remove (instead of renaming) the "false" title at the top of the figure
> - 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
> - and expect migration to a newer sphinx version to have all these changes
> cleaned for the next release.
>
> Any comments?
>
> Greetings,
> Harrissou
>
> [1]
> http://docs.qgis.org/2.14/fr/docs/user_manual/working_with_vector/vector_properties.html
> [2]
> http://docs.qgis.org/2.14/en/docs/documentation_guidelines/writing.html#figure
> [3]
> http://www.sphinx-doc.org/en/stable/config.html?highlight=figure#confval-numfig
> [4] https://github.com/qgis/QGIS-Documentation/issues/788
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20161021/429ae79a/attachment.html>