On Thu, Mar 4, 2010 at 7:10 AM, luigi scarso
<luigi.scarso@gmail.com> wrote:
On Thu, Mar 4, 2010 at 3:35 AM, James Fisher <
jameshfisher@gmail.com> wrote:
> - In my humble opinion, TeXies need to get out of the habit of
> 'self-documenting' TeX using TeX itself. TeX is not some replacement for
> all markup, it's for producing beautiful books (OK, and some presentations);
started with Latex209 ,I believe.
> So, thoughts?
Yes from http://sphinx.pocoo.org/
"Sphinx is a tool that makes it easy to create intelligent and
beautiful documentation"
but I believe that ConTeXt is better
" * Output formats: HTML (including Windows HTML Help) and LaTeX,
for printable PDF versions"
Are you suggesting to use LaTeX to document ConTeXt source ?
lol; I thought this might come up. I have a couple of replies to that:
(1) First and most important: I'm not suggesting that we use TeX to document things at all. I'm suggesting that ConTeXt documentation should be accessible to newcomers in the same format as 99% of all other projects: good old HTML. On the web (which you are), HTML is king. TeX and PDFs are no replacement for the interconnected power of the web. When I want a quick piece of information in <10 seconds, I do not want to consult a hand-collected folder of PDFs, or google for it and wait the age for a PDF to load. That kind of feeling, I guess, is the reason that the contextgarden wiki exists. But nor is Mediawiki is really not the most appropriate way to document a project. Wikis are messy and unstructured. They don't lend themselves well to the hierarchical kind of structure appropriate for representing a codebase. So I'm suggesting that ConTeXt be documented using a typical established documentation system.
(2) The docutils codebase (which manages reStructuredText) is modularized extremely well. Output formats can be written with a minimum of effort. The docutils document tree looks a lot like XML, and as such making ConTeXt output possible is just doing the standard XML-to-TeX conversion. I have in fact, while using ConTeXt, been writing a crude docutils ConTeXt writer (though quite a way to go).
About model of development: one developer is not so strange afterall .
In other situations maybe this is not adequate, in this situation
actually it's the best choice
(where for my experience "actually" goes
from 10year ago until now).
For example mkii is frozen while mkiv is at 50%, if we consider that
luatex 0.50 is at 50%, and luatex 1.0 will be 100%:
btw mkiv is really usable, not in some fuzzy alpha state (frozen is
not a bad word : tex is frozen from ~1990, pdftex is "cold", ie
changes a little, luatex is "hot")
I'm not sure what your point is here. That user contribution leads to 'featuritis'? I totally understand that being 'frozen' is not a bad thing; it effectively means 'having reached a state of perfection for the defined task' -- I don't think this has a connection with having one developer. More developers == faster rate of approach to the limit of perfection.
This model doesn't imply that you cannot contribute to the code base
but only that all contributions need to be validate (and possible
rejected) and integrate by developer,.
You can also contribute with third part modules, but they are not in
base code and in case of conflicts code base wins.
Sure thing -- revision control doesn't hinder that at all. If Hans doesn't want to merge someone else's changes to his (authoritative) copy of the repo, then he doesn't have to. DVCS != chaos.
There is no need for a public dcvs : for mkiv there is always one beta
version, the last one.
Errors will be fixed in next beta. This imply that you must be
prepared to patch your macros/stylesheets
to match with last version
This sounds circular to me: there's always one beta version *because* there's no revision control.
Patrick thinks
that a public git is a good idea and me too, but
one can always manage his personal dcvs --- which is a good idea to
understand code evolution on a particularly subject
(I believe the Arthur has an historical archive )
Sure, I do it for my pithy projects. All that I've learned is that I could even less do without it if my projects were large, like ConTeXt.
For comparison, luatex project is developed in "traditional" manner:
svn, bug tracker, manual (in context mkii ): the code base is in C
with target CWEB .
Mm, well, I kinda have the same opinions towards luatex documentation.
You can think at luatex as low-level layer which development is
driven by mkiv, a very high level layer,
which development is influenced by luatex itself (a sort of negative
feedback see http:// I understand that concern,en.wikipedia.org/wiki/Control_theory)
Again not sure what your point is -- LuaTeX and MKIV influence each other, so ..
As I said
the language and its semantic are particularly , almost unique.
Nothing strange that there is an ad hoc model of development
I don't know; I think the ties between language/semantics and the development model are pretty thin. I suspect that in the TeX community the characteristic of both comes from Knuth's character (extremely conservative and controlling, 'the codebase will stand with its flaws for all eternity for better or worse' kinda thing) rather than being an in-principle connection.
--
luigi