[Scons-dev] User-guide generation

[William Blevins]

Dirk,

Inline.

On Sun, Aug 21, 2016 at 3:44 PM, Dirk Bächle <tshortik at gmx.de> wrote:

> 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.
>

Maybe. I don't remember it taking that much long, but you might be right
here. My approach in this case would be to have the default scons target
include the #bin scripts but add an option to skip them. Perhaps this is
just a personal preference issue, but I like it when the default option
does it the most correct way even if that is slower. Does this opinion not
correlate directly to the SCons philosophy (IE. default target "." or
everything under the # directory)?


>
>
>>
>>     . 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 would argue that "the normal user" never runs the document building
scripts, so I don't see how that applies. Perhaps my viewpoint is odd in
that I was a user first and a developer second, but software development
has the concept of dog fooding. Is that not what I am doing? Using a tool
that I also work on?

As I said, I haven't been in this community long, so I don't know the
history of SCons (not really). How and why were some decisions made? As I
work on the code, those questions aren't irrelevant. Text has this way of
removing body language. I hope I don't sound combative because that's not
my intention. I just like being frank, and I like questions. I have a weird
mix of software development and tester experience, so questions just come
with the territory. I also tend to use emails like others use instant
messaging. I think it comes with the age demographic. This tends to annoy
people. Sorry :)


>
>
>>     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 at scons.org
> https://pairlist2.pair.net/mailman/listinfo/scons-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://pairlist2.pair.net/pipermail/scons-dev/attachments/20160821/f250b7c0/attachment.html>