[Scons-dev] User-guide generation

[Dirk Bächle]

Hi William,

On 20.08.2016 00:22, William Blevins wrote:
> Dirk,
>
> ...
>
> Right and I understand that there is documentation, and I use it when I have an issue. The problem that I have is that I have worked
> with the docs more than most (outside the maintainer team), and I always seem to forget about the #bin scripts. In my opinion, a
> good process is intuitive and doesn't have lots of manual steps. I think it would be a good idea to have the SConstruct in #doc/user
> to Execute the #bin scripts in order. I don't think it would cause any issues, but would make generating the docs a 1-step process.
> Is there a reason not to do something like this?
>

the main reason for this is, I guess, that the generation of examples needs a lot of time. And there are people out there that don't 
like seeing this step being repeated over and over again, whenever they make minor changes to the documents and want to receive 
"immediate" visual feedback.

>
>
>     . The normal user, only doing simple edits and changing text passages, shouldn't have to care about regenerating the output of
>     the examples. He can run the validate script, and then compile the user guide for example, such that he gets an idea how the
>     final PDF/HTML output might look like.
>     Everything beyond this point is in the scope of the actual release team. This separation is there to make it as easy as possible
>     for new contributors to add or amend documentation. The required validation ensures that the checked in and merged doc changes
>     by a user can be compiled into a correct document later on by a release manager, sort of justifying the usage of Docbook all
>     together.
>
>
> I don't see the harm in a regular developer getting a generated document that reflects the changes made. If I make changes to
> documents and regenerating the user guide doesn't show my changes, then it gets very puzzling.
>

I was talking about "the normal user" (read: occasional contributor), why do you now switch to what the "regular developer" can 
expect or not?
I understand that in your case both of these roles seem to coincide, but this is not true for the majority of people out there.

>
>     I hope this makes things a little clearer.
>
>     Finally, the UserGuide should also get recompiled when you change one of the chapter *.xml files. If this doesn't happen that
>     would clearly qualify as a bug...
>
>
> It rebuilds. We may want to change the wiki documentation though, because python-lxml does not appear to work correctly with the
> chunked guides index.html. I moved to python-libxml2 and python-libxslt1 and that seemed to make things happier.

Another option might be to find out *why* the python-lxml binding doesn't seem to work, and then make it doing so. ;)

Best regards,

Dirk