Re: [Boost-build] [doc] Sphinx.

Subject: Re: [Boost-build] [doc] Sphinx.
From: Raffi Enficiaud (raffi.enficiaud_at_[hidden])
Date: 2017-08-09 14:14:44

Le 09.08.17 à 14:14, Rene Rivera via Boost-build a écrit :
> On Wed, Aug 9, 2017 at 12:53 AM, Raffi Enficiaud via Boost-build
> <boost-build_at_[hidden] <mailto:boost-build_at_[hidden]>> wrote:
>
>     Le 09.08.17 à 04:02, Rene Rivera via Boost-build a écrit :
>
>         Ok, looking at the features of Sphinx more closely now.. Since
>         there are
>         various people here knowledgeable about Sphinx.
>
>         First question: Does Sphinx support PDF output *without* going
>         through
>         another output tool (i.e. not through docbook or latex)?
>
>
>     I believe not: they claim to generate Latex. But being able to
>     generate Latex is more than enough for the PDF output, isn't it?
>
>
> I don't know Latex (even though I edited some latex some decades ago) so
> all I can go by is what others claim it does.

I believe that, if you are in the point that you need to edit the latex 
of the generated Sphinx, there is something wrong in the workflow.

Yes, you will need to install Latex, but I prefer that rather than 
Sphinx ppl spending 80% of their resources on writing code that 
generates correct PDF files.

The only interface is:

 > make latexpdf

and this is calling pdflatex with the right options for you. It requires 
latex to be installed, as well as python of course, and make, a shell, 
etc...

>
>     What is your point?
>
>
> My point is that if that's the only option for PDF it's similar to
> quickbook in that it needs another tool to be installed. Having to
> install and correctly set up external tools raises the barrier to
> producing the good looking PDF docs. Something we are all too familiar
> with docbook. For example, I've tried two or three times over the past
> decade to get PDF output working for docbook without success.

This is not exactly similar. I have very little expertise in docbook, 
but when I see this:

https://stackoverflow.com/a/4728751/1617295

this looks like a nightmare, and needless to say it works well only on 
OSes that have very good committed package maintainers :)

(Now it sounds that I need to defend Latex :D )

Latex is available in on many OSes, is very well maintained and has a 
quite large set of users (95% of the scientists I know use latex, the 
others: I flag them as non-scientists anyway).

I believe this is not such a bad design that Sphinx decided to output 
Latex to generate PDF, because this looks to me like the "shortest path" 
to correct and good PDF.
Docbook OTOH decided not to do that, and ends up using a "longer path" 
(more tool involved), that is also more fragile (setup, maintenance, 
documentation).

In a previous post, you claimed that
"""
Popularity is not a wining argument around here ;-)
"""

I disagree:
* latex is popular in its own community, as a consequence, it is easy to use
* sphinx is popular in its own community, as a consequence, it is easy 
to use and to interface with latex
* docbook is not popular, as a consequence, the toolchain is weak and 
stayed so until now (and is de facto an impediment to its popularity).

You may see popularity as a cause or a consequence: it is both, and 
often it over weights the technical aspects on the long run.

*BUT* my claim "docbook vs. Sphinx" is not this at all. Docbook is hard 
to use, that is a given or an opinion.
The main rant I have against docbook is the markup, that basically needs 
a software more complex than just a text editor to be of any good usage, 
and is otherwise error prone, verbose, and requires a look of tweaking 
to have a decent output. All those facts made on average more work, 
either to editors that want to create documentation, or to developers 
that need to cover all the shortcomings of docbook with another layer 
(such as boostbook or quickbook).

*IF* you take "expressivity for content creation" argument first, and 
then suddenly need to generate PDF output, then one candidate is able to 
do it easily and almost seamlessly, the other one is adding new problems 
on top, but is still able to do it. In terms of features, they are 
equivalent though, just developers' life is different. The decision path 
for equivalent features would be: let's try to ease my file.

*IF* you take the same argument first, and now compare Sphinx to 
ASCIIDOCTOR, then which one gives you most flexibility and degrees of 
freedom for the output? is PDF possible or well integrated to Asciidoctor?

But tackling the problem the opposite direction (ie: "needs extra tool 
to generate PDF => so not good") is not the right decision pattern for me.

Best,
Raffi