User manual update: nth attempt

[Dirk Hohndel]

On Tue, Oct 27, 2015 at 11:08:51PM +0200, Willem Ferguson wrote:
> On 27/10/2015 20:00, Miika Turkia wrote:
> >Here is a diff of user-manual.html generated by me and the one
> >provided by you. There is clear difference in them. Now the question
> >is, what is different in our environments / git trees.
> >
> >miika
> >
> Miika,
> Do you get a left-handed toc with the latest build from master?
> I do not get it with the latest build.
> However, if I create a new html on my machine, using asciidoc, I get the
> left-handed toc.
> 
> My asciidoc instruction is reasonably straight forward:
> asciidoc -a toc -a toclevels=3 -a theme="compact_subsurface" -a
> themedir=$(pwd) -o user-manual.html user-manual.txt
> 
> I am not sure what the problem is. If I understand the make file in the
> Documents folder, the html user-manual on my machine is actually created
> using MY OWN installed asciidoc. The instruction in the make file appears
> quite ok to me.
> Nevertheless, the user-manual.html in git repo does NOT have a left-handed
> toc.
> I run asciidoc V8.6.9
> 
> I attach the html file generated by asciidoc on my machine using the
> user-manual.txt DOWNLOADED AS PART OF LATEST MASTER.
> So there is a make problem somewhere.

Yes there is.

When running asciidoc here in the source folder with the command above I
do get an html file with a left toc.

When building Subsurface it complains about a missing toc.css file which
is why I assumed that you added that and forgot to add it to the sources.
And then I went to bed. Apologies :-)

Running make out of tree, cmake creates this invocation for asciidoc:

asciidoc -a toc -a toclevels=3 -a themedir=/home/hohndel/subsurface/Documentation -a \
	theme=compact_subsurface -a stylesdir=/home/hohndel/subsurface/Documentation \
        -o /home/hohndel/subsurface-cmake-clang/Documentation/user-manual.html user-manual.txt

Which seems remarkably similar to your invocation above, except for the
added stylesdir argument... removing that fixes things.

But this of course made me curious why we had that in the first place and
this commit introduced it:

commit 12981030a563669a9560d4af71c389d9cad52380
Author: Sergey Starosek <sergey.starosek at gmail.com>
Date:   Tue Dec 10 13:47:39 2013 +0200

    Fix asciidoc CSS path
    
    Both JS and CSS resources need to be embedded into HTML
    
    Signed-off-by: Sergey Starosek <sergey.starosek at gmail.com>
    Signed-off-by: Dirk Hohndel <dirk at hohndel.org>

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8b539c729566..761f43bf6a67 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -19,7 +19,7 @@ $(OUT)$(DOCNAME).pdf: $(DOCSOURCE)
 
 $(OUT)$(HTMLDOC): $(DOCSOURCE)
 	@echo "if asciidoc isn't found no HTML documentation is produced but Subsurface is still functional"
-	$(ASCIIDOC) -a toc -a toclevels=3 -a themedir=$(PWD) -a theme=$(THEME) $< || true
+	$(ASCIIDOC) -a toc -a toclevels=3 -a themedir=$(PWD) -a theme=$(THEME) -a stylesdir=$(PWD) $< || true
 
 # Alternatively::
 $(OUT)$(DOCNAME).xhtml: $(DOCSOURCE)


Which makes me think that maybe there was a reason why this was there...

Sergey, this is two years ago, so I may be pushing my luck... but do you
remember why you needed to add this? It seems to build fine without this
and not to find a .css file when we use it.

Looking through the asciidoc documentation that makes sense because
stylesdir as used here makes it no longer look in the default location for
.css files. But we already find our css file because of the themedir
attribute, so why did we need to add stylesdir?

So for now I'll remove the stylesdir attribute and take Willem's patch.

/D