Date: Sun, 29 Dec 2013 05:08:28 -0800 (PST)
From: entot <ento.entotto@gmail.com>
To: lojban@googlegroups.com
Message-Id: <8306dbd5-1789-4def-8b65-810283aa58f5@googlegroups.com>
In-Reply-To: <20131227041501.GA21848@stodi.digitalkingdom.org>
References: <20131227041501.GA21848@stodi.digitalkingdom.org>
Subject: [lojban] Re: The CLL project, technical directions
MIME-Version: 1.0
Reply-To: lojban@googlegroups.com
Precedence: list
Mailing-list: list lojban@googlegroups.com; contact lojban+owners@googlegroups.com
Sender: lojban@googlegroups.com
Content-Type: multipart/alternative; 
	boundary="----=_Part_5905_25414065.1388322508664"
X-Spam_score: -0.1
X-Spam_score_int: 0
X-Spam_bar: /

------=_Part_5905_25414065.1388322508664
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

1.  =93Is there a better solution?"

There *are* tools for generating HTML and PDF from a single source. I think=
=20
capitalizing on one of them is a worthwhile option to consider.

In particular, Publican (based on docbook; maintained by RedHat) and Sphinx=
=20
(based on reStructuredText, a wiki-like markup language; official=20
documentation tool of Python) appear to be well-maintained.

Publican: https://fedorahosted.org/publican/
Sphinx: http://sphinx-doc.org/

Further in particular, I think Sphinx fits the overall bill:

- Has the concept of a glossary
  ex. glossary page:  http://sphinx-doc.org/glossary.html
  ex. link from main text to a glossary entry:=20
 http://sphinx-doc.org/tutorial.html (second paragraph, link titled "source=
=20
directory=94)

- Has the concept of a printed, page-numbered index
  ex. HTML:  http://sphinx-doc.org/genindex.html
  ex. PDF:  http://static.repoze.org/bfg-1.2a9-v3.pdf (scroll to the last=
=20
page)

- Actual books in paper have been produced using Sphinx
  http://sphinx-doc.org/examples.html#books-produced-using-sphinx

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

- Can be extended to define custom "tags", called "roles" in Sphinx:=20
corresponds to <cmavo/> etc.
  http://doughellmann.com/2010/05/defining-custom-roles-in-sphinx.html

- Can be extended to do custom rendering for a particular output format:=20
corresponds to <latex-verbatim/>
 =20
http://sphinx-doc.org/latest/ext/appapi.html#sphinx.application.Sphinx.add_=
node

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

That said, I also think the current setup can just work *if* its problems=
=20
are fixable by tweaking the workflow or documentation or whatever in a=20
low-cost way. I don't know enough about what the problem really is to make=
=20
a judgment.


2.  =93What needs to be streamlined to smoothly fix an issue"

- If the issue stems from the toolchain itself: a sandbox environment to=20
test small code snippets. Probably unit tests, or a very small subset of=20
the book that can be built in seconds.


3.  =93What if the initial conversion from local source to docbook was in=
=20
Haskell or Ruby, etc.?"

I want to make sure I understand why the initial conversion may be a=20
problem:

- Because it's in XSLT and few people know how to work with it?
- Because it's hard to maintain, i.e. tends to go spaghetti or easily get=
=20
broken when trying to fix something else, etc.?

Regardless, I myself would be a little more comfortable with something in=
=20
Python or Ruby, but I also think the overhead of getting familiar with a=20
new project's codebase would be about the same if it were in XSLT, Python=
=20
or Ruby.

I don't know enough about Haskell to comment.


4.  "I would better be able to help if..."

* Shorter build time. I=92ll have to re-check to give an actual number, but=
=20
for a full build, it was in the range of tens of minutes. Shorter build=20
time means less time for distraction.

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

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

--=20
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 e=
mail 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.

------=_Part_5905_25414065.1388322508664
Content-Type: text/html; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div><div>1. &nbsp;=93Is there a better solution?"</div><d=
iv><br></div><div>There *are* tools for generating HTML and PDF from a sing=
le source. I think capitalizing on one of them is a worthwhile option to co=
nsider.</div><div><br></div><div>In particular, Publican (based on docbook;=
 maintained by RedHat) and Sphinx (based on reStructuredText, a wiki-like m=
arkup language; official documentation tool of Python) appear to be well-ma=
intained.</div><div><br></div><div>Publican: https://fedorahosted.org/publi=
can/</div><div>Sphinx: http://sphinx-doc.org/</div><div><br></div><div>Furt=
her in particular, I think Sphinx fits the overall bill:</div><div><br></di=
v><div>- Has the concept of a glossary</div><div>&nbsp; ex. glossary page: =
&nbsp;http://sphinx-doc.org/glossary.html</div><div>&nbsp; ex. link from ma=
in text to a glossary entry: &nbsp;http://sphinx-doc.org/tutorial.html (sec=
ond paragraph, link titled "source directory=94)</div><div><br></div><div>-=
 Has the concept of a printed, page-numbered index</div><div>&nbsp; ex. HTM=
L: &nbsp;http://sphinx-doc.org/genindex.html</div><div>&nbsp; ex. PDF: &nbs=
p;http://static.repoze.org/bfg-1.2a9-v3.pdf (scroll to the last page)</div>=
<div><br></div><div>- Actual books in paper have been produced using Sphinx=
</div><div>&nbsp; http://sphinx-doc.org/examples.html#books-produced-using-=
sphinx</div><div><br></div><div>- Conversion from reStructuredText (reST) t=
o HTML and LaTeX is written in Python, not XSLT</div><div>&nbsp; - the conv=
ersion flow is</div><div>&nbsp; &nbsp; reST -&gt; HTML</div><div>&nbsp; &nb=
sp; reST -&gt; LaTeX -&gt; PDF</div><div>&nbsp; &nbsp; alternatively, reST =
-&gt; PDF (via a Python library called rst2pdf, which in turn uses reportla=
b)</div><div>&nbsp; &nbsp; - I don't know which route to PDF is better</div=
><div><br></div><div>- Can be extended to define custom "tags", called "rol=
es" in Sphinx: corresponds to &lt;cmavo/&gt; etc.</div><div>&nbsp; http://d=
oughellmann.com/2010/05/defining-custom-roles-in-sphinx.html</div><div><br>=
</div><div>- Can be extended to do custom rendering for a particular output=
 format: corresponds to &lt;latex-verbatim/&gt;</div><div>&nbsp; http://sph=
inx-doc.org/latest/ext/appapi.html#sphinx.application.Sphinx.add_node</div>=
<div><br></div><div>If we are to consider Sphinx as an alternative to the c=
urrent setup, I think it's best to prototype first with the set of construc=
ts from the book that we want to support, as there may be some features Sph=
inx 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.</div><div><br></div><di=
v>That said, I also think the current setup can just work *if* its problems=
 are fixable by tweaking the workflow or documentation or whatever in a low=
-cost way. I don't know enough about what the problem really is to make a j=
udgment.</div><div><br></div><div><br></div><div>2. &nbsp;=93What needs to =
be streamlined to smoothly fix an issue"</div><div><br></div><div>- 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.</div><div><br></div><div><br></div><div>3. &nbsp;=
=93What if the initial conversion from local source to docbook was in Haske=
ll or Ruby, etc.?"</div><div><br></div><div>I want to make sure I understan=
d why the initial conversion may be a problem:</div><div><br></div><div>- B=
ecause it's in XSLT and few people know how to work with it?</div><div>- Be=
cause it's hard to maintain, i.e. tends to go spaghetti or easily get broke=
n when trying to fix something else, etc.?</div><div><br></div><div>Regardl=
ess, I myself would be a little more comfortable with something in Python o=
r Ruby, but I also think the overhead of getting familiar with a new projec=
t's codebase would be about the same if it were in XSLT, Python or Ruby.</d=
iv><div><br></div><div>I don't know enough about Haskell to comment.</div><=
div><br></div><div><br></div><div>4. &nbsp;"I would better be able to help =
if..."</div><div><br></div><div>* Shorter build time. I=92ll have to re-che=
ck to give an actual number, but for a full build, it was in the range of t=
ens of minutes. Shorter build time means less time for distraction.</div><d=
iv><br></div><div>* An automated build server like Jenkins. For trivial fix=
es, people can just modify the source locally and make a pull request (or p=
ush to their own repo, depending on the setup) to let Jenkins build the ent=
ire 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.</div><div><br></div><div>* Regular hackathons. Having a fixed appoi=
ntment will help me in setting aside time for CLL. Timezone differences may=
 be problematic. I'm on GMT+0900.</div></div><div><br></div></div>

<p></p>

-- <br />
You received this message because you are subscribed to the Google Groups &=
quot;lojban&quot; group.<br />
To unsubscribe from this group and stop receiving emails from it, send an e=
mail to lojban+unsubscribe@googlegroups.com.<br />
To post to this group, send email to lojban@googlegroups.com.<br />
Visit this group at <a href=3D"http://groups.google.com/group/lojban">http:=
//groups.google.com/group/lojban</a>.<br />
For more options, visit <a href=3D"https://groups.google.com/groups/opt_out=
">https://groups.google.com/groups/opt_out</a>.<br />

------=_Part_5905_25414065.1388322508664--