Re: [Scons-dev] New SCons doc toolchain...

2013-05-09 Thread Gour 
On Tue, 26 Mar 2013 00:50:07 +0100
Dirk Bächle tshor...@gmx.de wrote:

 Hi developers,

- All processing is based on plain Python scripts, the only 
 additional dependencies are either lxml or libxml2.
  (for creating the PDF files, you also need to have a renderer
 like fop, xep or jw installed)
  XML parsing is now DOM-based, instead of using SAX.
- Uses a special SCons XSD, based on the Docbook v4.5 DTD/XSD.
- All documents (like MAN pages, User guide and also the 
 Tools/Builders docs in the src/engine folder)
  are valid against this XSD and can be easily re-validated after
 any changes by running a single script.
- The troff input files for the MAN pages have been converted to 
 Docbook (DocLifter still rocks!).
- Entities, the descriptions for Tools/Builders/Functions/CVars
 and the automatically created example
  outputs are supported as before.
- All document folders have SConstructs, together with the added 
 Docbook Tool you can directly create
  HTML and MAN pages. The User guide has its own titlepage design, 
 see the attached PDF for getting
  a first impression from a few selected pages.

I settled to use SCons for my PyQt project and was reading the User Manual
yesterday and e.g. found that the email addresses listed are wrong (e.g.
us...@scons.tigris.org) which led me to check how are docs handled in order to
know how to contribute some 'patches'.

So, I was a bit surprised that SCons uses Docbook toolchain considering that
some time ago project switched from SVN to (more pythonic) Mercurial, I wonder
why not using (more pythonic) reST/Sphinx which, imho, requires less admin
work and it provides lower-hanging fruit for potential contributors who are
probably more familiar with reST/Sphinx than Docbook.

Moreover, the current user manual is ~350p and not so complicated to require
the above-mentioned features.

I hope that you will find this email only as constructive feedback meant to
improve SCons project by simplifying doc toolchain in order to spend valuable
time of not-to-big developer's team on more important issues.

Of course, I greatly appreciate Dirk's work on improving the toolchain and my
proposal is in the same vein. :-)


Sincerely,
Gour

-- 
One must deliver himself with the help of his mind, and not 
degrade himself. The mind is the friend of the conditioned soul, 
and his enemy as well.

http://www.atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-09 Thread Dirk Bächle 

Hi Gour,

On 09.05.2013 10:33, Gour wrote:

On Tue, 26 Mar 2013 00:50:07 +0100
Dirk Bächle tshor...@gmx.de wrote:


[...]

I settled to use SCons for my PyQt project and was reading the User Manual
yesterday and e.g. found that the email addresses listed are wrong (e.g.
us...@scons.tigris.org) which led me to check how are docs handled in order to
know how to contribute some 'patches'.

So, I was a bit surprised that SCons uses Docbook toolchain considering that
some time ago project switched from SVN to (more pythonic) Mercurial, I wonder
why not using (more pythonic) reST/Sphinx which, imho, requires less admin
work and it provides lower-hanging fruit for potential contributors who are
probably more familiar with reST/Sphinx than Docbook.

Moreover, the current user manual is ~350p and not so complicated to require
the above-mentioned features.

I hope that you will find this email only as constructive feedback meant to
improve SCons project by simplifying doc toolchain in order to spend valuable
time of not-to-big developer's team on more important issues.


thanks a lot for trying out the new doc toolchain. It's still very fresh 
and there's probably a lot of room for improvement...including a rewrite 
to another input format (like asciidoc, reST, whatever).
So, we're very interested in hearing about first impressions from avid 
users like you.


If it were only about creating plain text with some graphics, you're 
right. This could easily be handled by a lot
of other toolchains. However, I'd like you to have a short look over the 
discussion at


  http://www.scons.org/wiki/DeveloperGuide/Documentation

and

  http://www.scons.org/wiki/DeveloperGuide/Documentation/Discussion

, respectively. There is also a description of the current 
implementation in the file doc/overview.rst. Together they might shed 
some light on why we (errm, I) finally chose Docbook.

If you have further thoughts or questions, please don't hesitate to ask.

Thanks again for your feedback.

Best regards,

Dirk


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-09 Thread Gour 
On Thu, 9 May 2013 17:06:35 -0400
Gary Oberbrunner ga...@oberbrunner.com wrote:

 I see this as an iterative process.  The first thing was to
 rationalize the tool chain and use one tool for everything.  Formerly
 we had a hodgepodge of stuff.  Now that it's decently organized,
 there's of course more work to be done to make the doc better, more
 beautiful and readable, and so on -- and we can consider switching to
 alternative tools too; at least everything parses and validates now!
 So it's conceivable to convert it if that makes sense.

Thank you for that. I was simply not aware about the whole context. :-(

Now it is clear and makes much more sense.

Once again, kudos to Dirk for his work on the doc toolchain which is often
thankless job.

 (By the way, I use git at work and for some other open source
 projects, and I have to say, even though it's more complicated and
 the doc is poor and the commands args are inconsistent, I like it a
 lot more than mercurial. Having the right core architecture and
 philosophy makes all the difference.)

Strangely enough, I was avoiding getting 'dirty' with Git always assuming
(prejudices, prejudices...) that's it's very (too) complicated to use, but now
I find it's very pleasurable and easy to use, even easier than some other DVCS
tool (darcs is still the king of UI, imho).


Sincerely,
Gour

-- 
When your intelligence has passed out of the dense forest 
of delusion, you shall become indifferent to all that has 
been heard and all that is to be heard.

http://www.atmarama.net | Hlapicina (Croatia) | GPG: 52B5C810


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-09 Thread Dirk Bächle 

Hello Gour,

On 09.05.2013 22:53, Gour wrote:

On Thu, 09 May 2013 12:14:29 +0200
Dirk Bächle tshor...@gmx.de wrote:

[...]

If it's good-enough for Python project docs itself, I believe it should be for
SCons as well.


that's okay...but to make me believe this as well, you (or someone else) 
has to deliver actual results. ;)
As I stated before in this thread, as long as the same functionality is 
kept regarding the automatic creation of examples (and the generated 
list of tools and builders, while delivering the same output formats we 
have now), a toolchain based on a Markdown processor gets my full support.



Knowledge of Docbook authoring is not very common in general and certainly not
within Python community, so I'm afraid that contributing docs to SCons project
would remain niche for a few people only.

Moreover, the current output of the manual shows that the complexity of the
markup used to write it is not in proportion the quality of output and
tweaking/theming is still, imho, much easier to do with Sphinx.
That's more because the stylesheets have been neglected in the past 
(obviously nobody wanted to fiddle with DSSSL) and because parts of the 
document processing relied on home-brewed SGML parsing without proper 
support for XML. Like this, not all valid XML/Docbook constructs would 
have worked, which held back people a little to use the full power of 
the Docbook stylesheets.

This can (and hopefully will) change now...


Finally, in regard to the argument of converting Docbook to something else,
there is wonderful tool called Pandoc (http://johnmacfarlane.net/pandoc/)
which is capable of reading Docbook markup and select it to several other
markup formats.


Then just try to convert a few SCons documents with it, and send us some 
selected pages (not the whole document!) of output samples.



Regards,

Dirk

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-09 Thread Bill Deegan 
In SCons as with all opensource.. words are ok, but functional tested,
documented pull requests are rare and priceless!

-Bill


On Thu, May 9, 2013 at 2:55 PM, Dirk Bächle tshor...@gmx.de wrote:

 Hello Gour,


 On 09.05.2013 22:53, Gour wrote:

 On Thu, 09 May 2013 12:14:29 +0200
 Dirk Bächle tshor...@gmx.de wrote:

 [...]


 If it's good-enough for Python project docs itself, I believe it should
 be for
 SCons as well.


 that's okay...but to make me believe this as well, you (or someone else)
 has to deliver actual results. ;)
 As I stated before in this thread, as long as the same functionality is
 kept regarding the automatic creation of examples (and the generated list
 of tools and builders, while delivering the same output formats we have
 now), a toolchain based on a Markdown processor gets my full support.


  Knowledge of Docbook authoring is not very common in general and
 certainly not
 within Python community, so I'm afraid that contributing docs to SCons
 project
 would remain niche for a few people only.

 Moreover, the current output of the manual shows that the complexity of
 the
 markup used to write it is not in proportion the quality of output and
 tweaking/theming is still, imho, much easier to do with Sphinx.

 That's more because the stylesheets have been neglected in the past
 (obviously nobody wanted to fiddle with DSSSL) and because parts of the
 document processing relied on home-brewed SGML parsing without proper
 support for XML. Like this, not all valid XML/Docbook constructs would have
 worked, which held back people a little to use the full power of the
 Docbook stylesheets.
 This can (and hopefully will) change now...


  Finally, in regard to the argument of converting Docbook to something
 else,
 there is wonderful tool called Pandoc (http://johnmacfarlane.net/**
 pandoc/ http://johnmacfarlane.net/pandoc/)
 which is capable of reading Docbook markup and select it to several other
 markup formats.


 Then just try to convert a few SCons documents with it, and send us some
 selected pages (not the whole document!) of output samples.


 Regards,

 Dirk


 __**_
 Scons-dev mailing list
 Scons-dev@scons.org
 http://two.pairlist.net/**mailman/listinfo/scons-devhttp://two.pairlist.net/mailman/listinfo/scons-dev

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-01 Thread Dirk Bächle 

On 29.04.2013 21:51, William Deegan wrote:

All,

I see the following when running bootstrap.py

[...]


Also I had to install the following (on ubuntu 10.04)
  sudo apt-get install python-libxml2 
python-libxslt1 python-epydoc fop python2.6-dev


Note that without the proper tools installed the build failed 
complaining about scons.1 missing.
Would it be possible to allow bootstrap.py to complete skipping the 
parts which won't build due to missing tools?




Okay,

I pushed a new revision. Creating all the doc outputs is happening in 
the build directory now. I also updated scons_dev_master.py and added a 
check for lxml/libxml2 to the SConscript for the doc folder. It skips 
the documentation step if neither of the required packages can be found.

Please update and check, if you find the time.

Meanwhile, I'll prepare the actual pull request.

Best regards,

Dirk

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-01 Thread Bill Deegan 
Dirk,

Should you also add fop or the other alternative to the scons_dev_master?

Thanks,
Bill


On Wed, May 1, 2013 at 11:54 AM, Dirk Bächle tshor...@gmx.de wrote:

  On 29.04.2013 21:51, William Deegan wrote:

 All,

  I see the following when running bootstrap.py

  [...]


  Also I had to install the following (on ubuntu 10.04)
sudo apt-get install python-libxml2
 python-libxslt1 python-epydoc fop python2.6-dev

  Note that without the proper tools installed the build failed
 complaining about scons.1 missing.
 Would it be possible to allow bootstrap.py to complete skipping the parts
 which won't build due to missing tools?


 Okay,

 I pushed a new revision. Creating all the doc outputs is happening in the
 build directory now. I also updated scons_dev_master.py and added a check
 for lxml/libxml2 to the SConscript for the doc folder. It skips the
 documentation step if neither of the required packages can be found.
 Please update and check, if you find the time.

 Meanwhile, I'll prepare the actual pull request.

 Best regards,

 Dirk


 ___
 Scons-dev mailing list
 Scons-dev@scons.org
 http://two.pairlist.net/mailman/listinfo/scons-dev


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-05-01 Thread Dirk Bächle 

On 01.05.2013 21:30, Bill Deegan wrote:

Dirk,

Should you also add fop or the other alternative to the 
scons_dev_master?


Thanks,
Bill



Isn't it in the list on your side? I can see it in my revision...and on 
the bitbucket commit.
The xep renderer is a commercial one, but there is a free trial 
download available.

So I can't add this one to the packages, sorry.

Dirk

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Russel Winder 
On Tue, 2013-04-23 at 19:21 +0200, Dirk Bächle wrote:
 On 23.04.2013 18:12, Russel Winder wrote:
[…]
  Uurrr… isn't lxml a wrapper over libxml2 to provide the ElementTree API
  (and other things like a validating parser and XPath).
 
 Yes, that appears to be true for libxml2 (the C library, that 
 python-lxml depends on)...but not python-libxml2 (the Python bindings), 
 which is the lib I'm actually talking about.

bootstrap.py picked up lxml on my system. I am assuming this is the
Python 2 in use rather than the vastly superior Python 3.3 ;-)

-- 
Russel.
=
Dr Russel Winder  t: +44 20 7585 2200   voip: sip:russel.win...@ekiga.net
41 Buckmaster Roadm: +44 7770 465 077   xmpp: rus...@winder.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder


signature.asc
Description: This is a digitally signed message part
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Dirk Bächle 

Hi Russel,

thanks a lot for all your comments. I won't go into detail about each 
one of them, but would like to say a few words in general.
There still may be some quirks with fonts or layouts and fop is 
certainly not state of the art for PDF rendering...whatever. To be 
honest, I don't care that much...if you do, I'll gladly accept your pull 
requests.
I tried to improve the overall procedure for creating the documents, 
especially for a user that wants to contribute by writing a paragraph or 
two for the manual or the UserGuide.
And I had some success with that, at least it was the best I could give 
and I, personally, am happy with the result.


So there it is now, and can be used by the SCons project. If you guys 
are not convinced or have better ideas, that's good. Let's talk about 
them and if they can support all the current features we need and look 
even prettier, that would be the way to go then.

I'm cool with that...
What I don't want to happen is, that we do nothing just because the 
fonts don't look pretty enough yet, or some hyphenations are still wrong.
I'd rather go into a possibly wrong direction first and then correct, 
instead of not moving at all and being stuck with SGML and troff.


Best regards,

Dirk

On 28.04.2013 08:41, Russel Winder wrote:

[...]

I think human being should never have to read or write XML, not even
DocBook/XML. XML-based toolchains are clearly now the norm in publishing
for re-purposing, but should this lead to requiring authors to write
DocBook/XML?


Yes, in our case I think it should. Because it allows us to validate the 
documents, such that we can put the main work load on the user, not us. ;)



[...]

Seriously, I do worry that using XML is a sufficient barrier to entry
that we will not be evolving the content of the documentation just the
form.


Well, troff is a barrier as well. Wouldn't it help to move away from 
that, as a first step?



Dirk deserves a prize for taking this on and doing what he has.
  


If we finally get a little bit of movement about this topic, that'll be 
enough of a prize to me. :)


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Russel Winder 
On Sun, 2013-04-28 at 11:35 +0200, Dirk Bächle wrote:
[…]
 What I don't want to happen is, that we do nothing just because the 
 fonts don't look pretty enough yet, or some hyphenations are still wrong.
 I'd rather go into a possibly wrong direction first and then correct, 
 instead of not moving at all and being stuck with SGML and troff.
[…]
 If we finally get a little bit of movement about this topic, that'll be 
 enough of a prize to me. :)

Given the current system is XML based, with xml files and in files
required, the new system is an improvement and should be accepted. We
can look at fonts, hyphenation, etc. as a consequence of getting some
movement and momentum into evolving things.

Switching to something other than XML-based is a medium- to long-term
thing that I would like to see happen. Improving the XML-based systems
now is something I would like to see happen. 

-- 
Russel.
=
Dr Russel Winder  t: +44 20 7585 2200   voip: sip:russel.win...@ekiga.net
41 Buckmaster Roadm: +44 7770 465 077   xmpp: rus...@winder.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder


signature.asc
Description: This is a digitally signed message part
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Gary Oberbrunner 
On Sun, Apr 28, 2013 at 10:06 AM, Russel Winder rus...@winder.org.ukwrote:

 Given the current system is XML based, with xml files and in files
 required, the new system is an improvement and should be accepted.


Glad you agree, I feel the same way.  This way all the doc uses the same
source language and in the same way, with a much more consistent (and
verifiable) pipeline.  I want to review some of the non-PDF generated stuff
to make sure it's all there (as well as the old system did anyway), but
Dirk, why don't you start prepping a pull request.  Once it's in we can
sweat the details (Russel's list is good to start).  Bill, what do you
think?


-- 
Gary
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Dirk Bächle 

On 28.04.2013 20:20, Gary Oberbrunner wrote:


On Sun, Apr 28, 2013 at 10:06 AM, Russel Winder rus...@winder.org.uk 
mailto:rus...@winder.org.uk wrote:


Given the current system is XML based, with xml files and in files
required, the new system is an improvement and should be accepted.


Glad you agree, I feel the same way.  This way all the doc uses the 
same source language and in the same way, with a much more consistent 
(and verifiable) pipeline.  I want to review some of the non-PDF 
generated stuff to make sure it's all there (as well as the old system 
did anyway), but Dirk, why don't you start prepping a pull request. 
 Once it's in we can sweat the details (Russel's list is good to 
start).  Bill, what do you think?




I am ready to prepare a pull request any time...if we all agree that the 
current status of my experimental branch is good enough to go, I'll 
latch on.
Would you rather like the pull request to be one single commit, or 
should I transplant all my single revisions for having a history that 
makes single changes/decisions more trackable?


Dirk


___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-28 Thread Gary Oberbrunner 
On Sun, Apr 28, 2013 at 2:44 PM, Dirk Bächle tshor...@gmx.de wrote:

  On 28.04.2013 20:20, Gary Oberbrunner wrote:


 On Sun, Apr 28, 2013 at 10:06 AM, Russel Winder rus...@winder.org.ukwrote:

 Given the current system is XML based, with xml files and in files
 required, the new system is an improvement and should be accepted.


 Glad you agree, I feel the same way.  This way all the doc uses the same
 source language and in the same way, with a much more consistent (and
 verifiable) pipeline.  I want to review some of the non-PDF generated stuff
 to make sure it's all there (as well as the old system did anyway), but
 Dirk, why don't you start prepping a pull request.  Once it's in we can
 sweat the details (Russel's list is good to start).  Bill, what do you
 think?


 I am ready to prepare a pull request any time...if we all agree that the
 current status of my experimental branch is good enough to go, I'll latch
 on.


The only thing I might suggest prior to a pull request would be to build
the docs into the build dir.


 Would you rather like the pull request to be one single commit, or should
 I transplant all my single revisions for having a history that makes single
 changes/decisions more trackable?


In a git world, I like to clean up commits into small but meaningful units.
 In mercurial it's not as easy, but if you can do it it's helpful for
forensics.


-- 
Gary
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-27 Thread Gary Oberbrunner 
Where do we stand on this?  The User guide definitely looks a lot prettier
with Dirk's system, and it seems to have all the same sections as the old
guide (the layout is a bit denser so it comes in at 286 pages rather than
337).  The title page font is a bit too big but I'm sure that can be easily
adjusted.

What do people think?



On Wed, Apr 24, 2013 at 7:48 AM, Gary Oberbrunner ga...@oberbrunner.comwrote:

 I don't see the bricks errors anymore, good.

 I'm not sure everything is getting built into build/ however.  For
 instance the *_xi.xml and *_db.xml files are getting created in the doc/man
 dir. At one point I thought I had changed something and they didn't get
 rebuilt, which is why I noticed.  (Might be missing a dependency
 somewhere?)


 On Tue, Apr 23, 2013 at 5:17 PM, Dirk Bächle tshor...@gmx.de wrote:

 On 23.04.2013 02:28, Gary Oberbrunner wrote:

 Works much better now.  I re-cloned and installed fop and now it builds.
  I do get some errors about the bricks SVG file:

 SEVERE: svg graphic could not be built: file:/home/user/src/scons_doc_**
 toolchain/doc/design/**titlepage/SConsBuildBricks_**path.svg:0
 The URI file:/home/dirk/workspace/**docs/scons/xincluded_**
 userguide/user/titlepage/**bricks.jpg
 on element image can't be opened because:
 The URI can't be opened:
 /home/dirk/workspace/docs/**scons/xincluded_userguide/**user/titlepage/bricks.jpg
 (No such file or directory)


 Yeah,

 sorry about that...the SVG file contained an absolute path to the
 included JPG file. This is now fixed with the latest commit.


 Dirk


 __**_
 Scons-dev mailing list
 Scons-dev@scons.org
 http://two.pairlist.net/**mailman/listinfo/scons-devhttp://two.pairlist.net/mailman/listinfo/scons-dev




 --
 Gary




-- 
Gary
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-23 Thread Russel Winder 
On Mon, 2013-04-22 at 23:44 +0200, Dirk Bächle wrote:
[…]
 Make sure that you have fop and one of the XML Python bindings 
 installed (lxml or libxml2)...the latter is to be preferred because it 
 is much faster, but both should work fine now.

Uurrr… isn't lxml a wrapper over libxml2 to provide the ElementTree API
(and other things like a validating parser and XPath).

-- 
Russel.
=
Dr Russel Winder  t: +44 20 7585 2200   voip: sip:russel.win...@ekiga.net
41 Buckmaster Roadm: +44 7770 465 077   xmpp: rus...@winder.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder


signature.asc
Description: This is a digitally signed message part
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-23 Thread Dirk Bächle 

On 23.04.2013 18:12, Russel Winder wrote:

On Mon, 2013-04-22 at 23:44 +0200, Dirk Bächle wrote:
[…]

Make sure that you have fop and one of the XML Python bindings
installed (lxml or libxml2)...the latter is to be preferred because it
is much faster, but both should work fine now.

Uurrr… isn't lxml a wrapper over libxml2 to provide the ElementTree API
(and other things like a validating parser and XPath).


Yes, that appears to be true for libxml2 (the C library, that 
python-lxml depends on)...but not python-libxml2 (the Python bindings), 
which is the lib I'm actually talking about.


Regards,

Dirk

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-22 Thread Dirk Bächle 

Gary,

On 22.04.2013 02:21, Gary Oberbrunner wrote:




On Sun, Apr 21, 2013 at 5:57 PM, Dirk Bächle tshor...@gmx.de 
mailto:tshor...@gmx.de wrote:


Hi Gary,

On 21.04.2013 23 tel:21.04.2013%2023:38, Gary Oberbrunner wrote:


[...]


Hi, Dirk!

I just cloned this on my Linux box (Ubuntu 11.10 - also tried
12.04), but running scons bootstrap.py gives errors:

scons: *** [design.xml] XMLSyntaxError : Specification mandate
value for attribute object, line 1, column 31
scons: building terminated because of errors.



I was able to reproduce the error on a SuSE 11 box. The lxml support for 
the Docbook Tool needed a few fixes, I uploaded 2 commits to the 
new_doc_toolchain branch. Please update and try again...


While doing some further testing, I discovered that jw can render PDF 
from Docbook files, but it doesn't cope with XML input (only SGML) in 
all cases. That's why I removed it from the list of PDF renderers for 
the toolchain, so only fop and xep are left now.


Make sure that you have fop and one of the XML Python bindings 
installed (lxml or libxml2)...the latter is to be preferred because it 
is much faster, but both should work fine now.


Best regards,

Dirk

___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-22 Thread Gary Oberbrunner 
Works much better now.  I re-cloned and installed fop and now it builds.  I
do get some errors about the bricks SVG file:

SEVERE: svg graphic could not be built:
file:/home/user/src/scons_doc_toolchain/doc/design/titlepage/SConsBuildBricks_path.svg:0
The URI
file:/home/dirk/workspace/docs/scons/xincluded_userguide/user/titlepage/bricks.jpg
on element image can't be opened because:
The URI can't be opened:
/home/dirk/workspace/docs/scons/xincluded_userguide/user/titlepage/bricks.jpg
(No such file or directory)

and various warnings about paragraphs overflowing their space, but it does
all build OK.

Bill: the new User Guide has a ToC but no index.  I put a copy at
http://www.oberbrunner.com/temp/scons-user.pdf and
http://www.oberbrunner.com/temp/scons-man.pdf.





On Mon, Apr 22, 2013 at 5:44 PM, Dirk Bächle tshor...@gmx.de wrote:

  Gary,


 On 22.04.2013 02:21, Gary Oberbrunner wrote:




 On Sun, Apr 21, 2013 at 5:57 PM, Dirk Bächle tshor...@gmx.de wrote:

 Hi Gary,

 On 21.04.2013 23:38, Gary Oberbrunner wrote:


 [...]


 Hi, Dirk!

 I just cloned this on my Linux box (Ubuntu 11.10 - also tried 12.04),
 but running scons bootstrap.py gives errors:

 scons: *** [design.xml] XMLSyntaxError : Specification mandate value for
 attribute object, line 1, column 31
 scons: building terminated because of errors.


 I was able to reproduce the error on a SuSE 11 box. The lxml support for
 the Docbook Tool needed a few fixes, I uploaded 2 commits to the
 new_doc_toolchain branch. Please update and try again...

 While doing some further testing, I discovered that jw can render PDF
 from Docbook files, but it doesn't cope with XML input (only SGML) in all
 cases. That's why I removed it from the list of PDF renderers for the
 toolchain, so only fop and xep are left now.

 Make sure that you have fop and one of the XML Python bindings installed
 (lxml or libxml2)...the latter is to be preferred because it is much
 faster, but both should work fine now.

 Best regards,

 Dirk


 ___
 Scons-dev mailing list
 Scons-dev@scons.org
 http://two.pairlist.net/mailman/listinfo/scons-dev




-- 
Gary
___
Scons-dev mailing list
Scons-dev@scons.org
http://two.pairlist.net/mailman/listinfo/scons-dev

Re: [Scons-dev] New SCons doc toolchain...

2013-04-21 Thread Gary Oberbrunner 
On Sun, Apr 21, 2013 at 5:57 PM, Dirk Bächle tshor...@gmx.de wrote:

 Hi Gary,

 On 21.04.2013 23:38, Gary Oberbrunner wrote:


 [...]


 Hi, Dirk!

 I just cloned this on my Linux box (Ubuntu 11.10 - also tried 12.04), but
 running scons bootstrap.py gives errors:

 scons: *** [design.xml] XMLSyntaxError : Specification mandate value for
 attribute object, line 1, column 31
 scons: building terminated because of errors.

 (repeats a few times).  This prevents it from building doc/man/scons.1.

 I'm on the new_doc_toolchain branch, 6822ec.  Do I perhaps have an
 out-of-date dependency or something?


 this is strange, mainly because design.xml doesn't have anything to do
 with building the MAN pages. It works fine on my side (Ubuntu Linux 12.04.2
 LTS)...did you run the SConstruct for the doc/man subfolder with a
 revision from new_doc_toolchain before? Then, maybe some leftover files
 could be responsible for this error.


It's a brand new clone of your repo, nothing else in there.  It's probably
some tool it's using that I'm missing, or getting the wrong version of, or
something?


 I have never seen this message and at the moment don't know what it
 actually means and where the problem is. What happens if you cd into the
 doc/man folder (or any of the other documents) and call:

   python ../../scr/script/scons.py

 such that only the doc outputs get built? Does that work?


No, it fails right away:

user@lubuntu:~/src/scons_doc_toolchain$ cd doc/man
user@lubuntu:~/src/scons_doc_toolchain/doc/man$ python
../../src/script/scons.py
SCons import failed. Trying to run from source directory
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
scons: *** [scons-time_db.xml] XMLSyntaxError : Specification mandate value
for attribute object, line 1, column 31
scons: building terminated because of errors.

Oddly, it doesn't print out the command it's executing to build
scons-time_db.xml, but clearly it's related to this:
env.DocbookXslt('%s_db.xml' % target, '%s_xi.xml' % target,
xsl='../xslt/to_docbook.xslt')

I put a few print stmts in that function, and on my machine it's using lxml.

I tried prefer_cmdline and I get a slew of other errors:

scons-time_xi.xml:1: parser error : Specification mandate value for
attribute object
lxml.etree._ElementTree object at 0x886456c
^
scons-time_xi.xml:1: parser error : attributes construct error
lxml.etree._ElementTree object at 0x886456c
^
scons-time_xi.xml:1: parser error : Couldn't find end of Start Tag
lxml.etree._ElementTree line 1
lxml.etree._ElementTree object at 0x886456c
^
scons-time_xi.xml:1: parser error : Extra content at the end of the document
lxml.etree._ElementTree object at 0x886456c
^
unable to parse scons-time_xi.xml
scons: done building targets.

... so I think scons-time_xi.xml was created badly because that line is the
only line in that file.  If I remove it and try again (still using
prefer_cmdline), it gets farther:

scons: Building targets ...
/usr/bin/xmllint --xinclude scons-time.xml  scons-time_xi.xml
/usr/bin/xsltproc -o scons-time_db.xml ../xslt/to_docbook.xslt
scons-time_xi.xml
/usr/bin/xsltproc -o scons-scons-time.fo pdf.xsl scons-time_db.xml
Making portrait pages on letter paper (8.5inx11in)
/usr/bin/xsltproc -o scons-scons-time.html html.xsl scons-time_db.xml
/usr/bin/jw -fo scons-scons-time.fo -pdf scons-scons-time.pdf
Usage: jw [options] sgml_file
where options are:
  -f|--frontend frontend:  Specify the frontend (source format)
   (default is docbook)
  -b|--backend backend:  Specify the backend (destination format)
   (default is html)
  -c|--cat file:  Specify an extra SGML open catalog
  -n|--nostd:  Do not use the standard SGML open catalogs
  -d|--dsl file|default|none: Specify an alternate style sheet
   (default is to use the default stylesheet)
  -l|--dcl file:  Specify an alternate SGML declaration
   (usual ones like xml.dcl get detected automatically)
  -s|--sgmlbase path:  Change base directory for SGML distribution
   (usually /usr/share/sgml)
  -p|--parser program:  Specify the parser if several are installed
(jade or openjade)
  -o|--output directory:  Set output directory
  -u|--nochunks:  Output only one big file
   (overrides the stylesheet settings)
  -i|--include section:  Specify a SGML marked section to include
   (should be marked as ignore in the SGML text)
  -w|--warning warning_type|list: Control warnings or display the allowed
warning types
  -e|--errors error_type|list: Control errors or display the allowed
error types
  -h|--help:  Print this help message and exit
  -V variable[=value]:  Set a variable
  -v|--version:  Print the version and exit
scons: *** [scons-scons-time.pdf] Error 1







 Also, can you properly validate all documents by calling

   python bin/docs-validate.py

 in the top-level dir?