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

[Russel Winder]

On Sat, 2013-04-27 at 22:28 -0400, Gary Oberbrunner wrote:

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


I have been too busy to do the work needed to have an opinion that
should be taken serious note of, but I cloned the repository, switched
to the branch and ran bootstrap.py. Some responses…

I got various warnings from fop, especially about "margin-left" and
"margin-right". Most of the fonts required I don't have, so lots of font
substitutions. Also lots of problems with fixed width tables. Not to
mention complaining about lack of "server-api" in /usr/share/java.

Masses of paragraph overflows, often by huge amounts like 48pt.

Lots of hyphenations in monospace font words – fortunately none I saw in
normal text.

After all the Python byte compiling I get lots of weird stuff about
"adding 'PURELIB/scons-2.1.0.alpha.yyyymmdd/SCons/" which seems
fundamentally wrong somewhere.

Finally I get:

        Warning: Can't read registry to find the necessary compiler setting
        Make sure that Python modules _winreg, win32api or win32con are installed.
        Traceback (most recent call last):
          File "/home/Checkouts/Mercurial/SCons_Doc_Toolchain/build/scons/setup.py", line 414, in <module>
            distutils.core.setup(**arguments)
          File "/usr/lib/python2.7/distutils/core.py", line 152, in setup
            dist.run_commands()
          File "/usr/lib/python2.7/distutils/dist.py", line 953, in run_commands
            self.run_command(cmd)
          File "/usr/lib/python2.7/distutils/dist.py", line 972, in run_command
            cmd_obj.run()
          File "/usr/lib/python2.7/distutils/command/bdist_wininst.py", line 189, in run
            self.create_exe(arcname, fullname, self.bitmap)
          File "/usr/lib/python2.7/distutils/command/bdist_wininst.py", line 271, in create_exe
            file.write(self.get_exe_bytes())
          File "/usr/lib/python2.7/distutils/command/bdist_wininst.py", line 366, in get_exe_bytes
            raise DistutilsFileError, str(msg) + ', %s not included in the Debian packages.' % filename
        NameError: global name 'DistutilsFileError' is not defined
        scons: *** [build/scons/dist/scons-2.1.0.alpha.yyyymmdd.win32.exe] Error 1

However, I have PDFs which I guess is what the exercise is about?

The page size is US Letter which sucks. A proper page size such as A4
would be far less "only the USA exists". Perhaps A4 should be the norm
with a special option for those who will not conform to international
standards, even if they actually have no viable choice.

The document is all Helvetica, Courier and Times, which would not be my
choice of fonts. But I guess this might be a font substitution thing?

Is fully justified better than ragged right? 

I think the red rules need to be not red. Probably just leave them
black.

I think Steven Knight should not be the sole recognised author and
copyright owner. Clearly he has a role but I think it not right for the
status quo to remain the state.

This raises the issue, that if there is a SCons Foundation and it is a
live entity, and the trustees are available for meetings and decision
making, then it should own the copyrights in these documents.

Too much indent in the grey boxes.

Section head fonts too large with respect to the body text font.

Many chapter titles too long for the space available; auto line breaking
leads to ugly chapter titles.

The grey boxes are a great improvement. Probably need different grey
boxes for code and for shell to distinguish them; the indent level does
have good affordance.

I think it is great that Dirk has put the effort into actually getting
something moving on this.

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?

Clearly LaTeX, even XeLaTeX, has many of the same barriers to entry as
DocBook/XML, but nowhere near as much. Using a binary format system such
as ODF is not reasonable since it is a binary blob system and imposing
formatting using such a format is unreasonable: Industry standard
toolchain for books just now seems to be author supplies Word format,
publishers convert to InDesign and start from scratch.

Having just been through this search I can attest that Markdown is not
up to the task of writing big documents. Nor is reStructure Text per se,
though Sphinx makes it feasible. AsciiDoc appears to be the market
leader via the AsciiDoc(tor) tool chain.  In the end we decided to
author in XeLaTeX anyway and find a way of delivering Word format files
to the publisher. (I know, this sucks, but we refuse to deal with binary
blobs since we insist on DVCS.)

Did I mention XML is not a good source form for humans?

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.

Dirk deserves a prize for taking this on and doing what he has.
 
-- 
Russel.
=============================================================================
Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder at ekiga.net
41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel at winder.org.uk
London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
Url : <http://two.pairlist.net/pipermail/scons-dev/attachments/20130428/ea8a8c38/attachment.pgp>