Re: [lojban] Re: The CLL project, technical directions

[Robin Lee Powell <rlpowell@digitalkingdom.org>]

On Sun, Dec 29, 2013 at 05:08:28AM -0800, entot wrote:
> 1.  “Is there a better solution?"
> 
> There *are* tools for generating HTML and PDF from a single
> source. I think capitalizing on one of them is a worthwhile option
> to consider.

Of course, but all the ones I've looked at have fallen short.

> In particular, Publican (based on docbook; maintained by RedHat)

Nope; uses wkhtmltopdf , which generates PDFs that use named
references instead of page numbered references.  No good.

(I've looked at *SO MANY* such systems ;_;)

> and Sphinx (based on reStructuredText, a wiki-like markup
> language; official documentation tool of Python) appear to be
> well-maintained.
> 
> Sphinx: http://sphinx-doc.org/
> 
> Further in particular, I think Sphinx fits the overall bill:

Now *this*.  *THIS*.  This is genuinely impressive.  The only
serious problem is that it's a completely different markup format
from what we currently have and hence I'd have to convert
everything, but that's not necessarily a serious problem.

My hat is off to you for finding a serious contender.  I'll deal
with it being Python on my own :)  (nothing against Python, I've
just managed to avoid learning it for 20 years and was kind of
perversely proud of the accomplishment) and take a serious look at
this.

Thank you very much.

In my own defense, I *did* look at reST, but not sphinx; non-sphinx
reST has no indexes.  IIRC.

> - Conversion from reStructuredText (reST) to HTML and LaTeX is written in 
> Python, not XSLT
>   - the conversion flow is
>     reST -> HTML
>     reST -> LaTeX -> PDF
>     alternatively, reST -> PDF (via a Python library called rst2pdf, which 
> in turn uses reportlab)
>     - I don't know which route to PDF is better

That's distinctly not bad.

[snip various further neatness]

> If we are to consider Sphinx as an alternative to the current
> setup, I think it's best to prototype first with the set of
> constructs from the book that we want to support, as there may be
> some features Sphinx is missing. The last statement implies I'm
> not an expert on the ins and outs of Sphinx. I did use it for work
> once though.

I completely agree.  Chapter 2 is the canonical test case.  If it
can do Chapters 2, 19, and any one other, that would be a complete
proof of concept.

> 2.  “What needs to be streamlined to smoothly fix an issue"
> 
> - If the issue stems from the toolchain itself: a sandbox environment to 
> test small code snippets. Probably unit tests, or a very small subset of 
> the book that can be built in seconds.

That last part is a good idea regardless.

> 3.  “What if the initial conversion from local source to docbook was in 
> Haskell or Ruby, etc.?"
> 
> I want to make sure I understand why the initial conversion may be a 
> problem:
> 
> - Because it's in XSLT and few people know how to work with it?

Yes.

> - Because it's hard to maintain, i.e. tends to go spaghetti or
> easily get broken when trying to fix something else, etc.?

Yes, but mostly the other one.

> 4.  "I would better be able to help if..."
> 
> * Shorter build time. I’ll have to re-check to give an actual
> number, but for a full build, it was in the range of tens of
> minutes. Shorter build time means less time for distraction.

Hours, actually.  I don't know how much I can fix that.

> * An automated build server like Jenkins. For trivial fixes,
> people can just modify the source locally and make a pull request
> (or push to their own repo, depending on the setup) to let Jenkins
> build the entire book and archive the result for inspection. Long
> build time may not be much of a problem if a build server were in
> place. I can help with setting one up.

Oh, so people would work on their own copy of the repo on their own
machines, but vrici would take their source and Do The Thing (tm)?

That sounds emminently doable.

> * Regular hackathons. Having a fixed appointment will help me in
> setting aside time for CLL. Timezone differences may be
> problematic. I'm on GMT+0900.

The complete fullness of my life is also an issue, but yes, this
would almost certainly help.

-Robin

-- 
You received this message because you are subscribed to the Google Groups "lojban" group.
To unsubscribe from this group and stop receiving emails from it, send an email to lojban+unsubscribe@googlegroups.com.
To post to this group, send email to lojban@googlegroups.com.
Visit this group at http://groups.google.com/group/lojban.
For more options, visit https://groups.google.com/groups/opt_out.