[NTG-context] Occasional words sticking out from flush-right

James Fisher jameshfisher at gmail.com
Thu Mar 4 15:25:13 CET 2010


On Thu, Mar 4, 2010 at 7:10 AM, luigi scarso <luigi.scarso at gmail.com> wrote:

> On Thu, Mar 4, 2010 at 3:35 AM, James Fisher <jameshfisher at 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);
> I think that "self-documenting" in TeX is 20year olds now --- it
> 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<http://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
>
> ___________________________________________________________________________________
> If your question is of interest to others as well, please add an entry to
> the Wiki!
>
> maillist : ntg-context at ntg.nl /
> http://www.ntg.nl/mailman/listinfo/ntg-context
> webpage  : http://www.pragma-ade.nl / http://tex.aanhet.net
> archive  : http://foundry.supelec.fr/projects/contextrev/
> wiki     : http://contextgarden.net
>
> ___________________________________________________________________________________
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.ntg.nl/pipermail/ntg-context/attachments/20100304/3e0423d1/attachment.html>


More information about the ntg-context mailing list