Numbered paragraphs

[Luc Saffre]

Hi

I would like to migrate a series of documents from LibreOffice to Sphinx. Here is an example (it's in German, but watch the paragraph numbering and headings):

https://saffre-rumma.net/dl/Software-Wartungsvertrag.pdf

I cannot migrate these documents because I didn't yet manage to implement this style of continuous paragraph numbering.
This style is used by other author as well. Here is an example:

http://www.vatican.va/content/francesco/en/encyclicals/documents/papa-francesco_20201003_enciclica-fratelli-tutti.html

How would I do this in Sphinx? 
I definitively do not want to number the paragraphs manually.
The only idea I had so far is to define a directive and a role like this:

.. step:: x
  :value: 1
  :style: ({})

Title
=====

:step:`x` first paragraph blabla

Section heading
---------------

:step:`x` second paragraph blabla


Does anybody do something similar? I didn't yet implement my idea because I'd prefer to join some existing effort rather than reinventing the wheel.

Luc

[jfbu]

Hi,

Le 27/02/2021 à 11:31, Luc Saffre a écrit :
> Hi
>
> I would like to migrate a series of documents from LibreOffice to Sphinx. Here is an example (it's in German, but watch the paragraph numbering and headings):
>
> https://saffre-rumma.net/dl/Software-Wartungsvertrag.pdf
>

I have good and bad news.


I will start with the bad news: although TeX (the program underlying LaTeX, which is but a big set of macros on top of it) has a construct called ``\everypar`` which in the theory could allow easily this type of things,

1. in fact paragraphs are everywhere in TeX for example in tables, but also in internal constructions for measurement, so although it is easy in TeX per se with a manually written document, it is hard to automatize,

2. worse, LaTeX uses the TeX ``\everypar`` for its own purposes (which typically help trigger infarious error messages such as "missing \item" which either you don't understand, or you understand after spending the needed months or years learning the TeX macro language and reading the LaTeX sources), and it is very complicated for user to manipulate it, *even* with manually written document. You can expect there are some packages providing the thing, but you can be certain they break something else.


Now the good news (and then the even better one).

The good news is that LaTeX 2021 will probably incorporate some mechanisms at core level to allow user hooks at start and end of paragraphs in a controlled way. You can see the gory details here

https://github.com/latex3/latex2e/blob/develop/base/ltpara.dtx

There was some discussion there (in fact the above development is a bit of a worry to me from Sphinx side)

https://github.com/latex3/latex2e/pull/506

For the long terms goal of the LaTeX team see

https://www.latex-project.org/publications/indexbytopic/pdf/


Now the even better news is that Sphinx 3.5.0 (rather 3.5.1...) added an explicit mark-up at each start of paragraph.

So, for a simple document as the one you link to above, it is very easy to achieve what you want.

(I mean very easy if you don't mind addint some LaTeX syntax to conf.py...)

Besides, it is safer to use Sphinx mark-up than the future LaTeX 2021 hooks, because the Sphinx mark-up only applies to real paragraphs in document and not to internal paragraphs sometimes used for measuring purposes.

Here is what you can add to conf.py

```
latex_elements = {
'preamble': r"""
% keep a copy or original meaning if we want to locally use it
% via raw directive
\let\originalsphinxAtStartPar\sphinxAtStartPar
\newcounter{myparacounter}%
\newcommand\myownAtStartPar{%
\refstepcounter{myparacounter}%
% add the text styling commands (bold, italic, change of font...) if desired
(\themyparacounter) % leaving a space after closing parenthesis
}%
\newcommand\triggermyownparastart{\let\sphinxAtStartPar\myownAtStartPar}%
\newcommand\revertmyownparastart{\let\sphinxAtStartPar\originalsphinxAtStartPar}%
% now we activate our own
\triggermyownparastart
""",
}
```

You can also do things like

\newcounter{myparacounter}[chapter]

so that it is reset at each "\chapter" command encountered in latex.

Or redefine \themyparacounter (etc... check LaTeX tutorials) to incorporate surrounding chaper, section, subsection whatever number (if secnumdepth setting numbers them)

The above is a bit bulky because I added extra things so that you can do

.. raw:: latex

\revertmyownparastart

do cancel,

and

.. raw:: latex

\triggermyownparastart

to reactivate


(perhaps around tables or other things where the numbering of paragraphs is unexpected)

Hope it helps

You must have Sphinx 3.5.1 or later for this

LaTeXperts tidbit of info: you may worry in the above that the customizing completely earse the original Sphinx code in the start paragraph hook. But no need to worry, this code is only to work-around a TeX limitation of not hyphenating the very first word of a paragrah, so if one adds as above a paragraph numbering, we can forget about that TeX limitation, because nothing next will be the very first word anymore. However in table cells, where this limitation is more likely to cause problems and where we don't want our paragraph counting (especially as tabulary typesets at least twice internally so might step twice the counter), it is needed to use the Sphinx 3.5 fix, and for this reason I added the needed mechanism \revertmyownparastart which does that.

Jean-François

> I cannot migrate these documents because I didn't yet manage to implement this style of continuous paragraph numbering.
> This style is used by other author as well. Here is an example:
>
> http://www.vatican.va/content/francesco/en/encyclicals/documents/papa-francesco_20201003_enciclica-fratelli-tutti.html
>
> How would I do this in Sphinx?
> I definitively do not want to number the paragraphs manually.
> The only idea I had so far is to define a directive and a role like this:
>
> .. step:: x
>   :value: 1
>   :style: ({})
>
> Title
> =====
>
> :step:`x` first paragraph blabla
>
> Section heading
> ---------------
>
> :step:`x` second paragraph blabla
>
>
> Does anybody do something similar? I didn't yet implement my idea because I'd prefer to join some existing effort rather than reinventing the wheel.
>
> Luc
>

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com <mailto:sphinx-users...@googlegroups.com>.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/c18622fa-ce62-3a2f-e8de-4f6a7820cdf6%40gmail.com <https://groups.google.com/d/msgid/sphinx-users/c18622fa-ce62-3a2f-e8de-4f6a7820cdf6%40gmail.com?utm_medium=email&utm_source=footer>.

[jfbu]

Hi again,

only now I realize the question was not only for pdf output via make latexpdf....


sorry, but as the first linked document was a PDF, I focused on that


obviously you don't want to do what I suggest if also targeting other outputs


then you should probably hook via a Sphinx extension into the "paragraph" nodes,


hope someone more competent than me can intervene here,

Best

Jean-François

Le 27/02/2021 à 11:31, Luc Saffre a écrit :

[Luc Saffre]

Yes, in a first phase I will indeed just want html output. Sorry for not having mentioned it in my original post.

Luc