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
_______________________________________________
Scons-dev mailing list
Scons-dev@scons.org
https://pairlist2.pair.net/mailman/listinfo/scons-dev
