Re: Occasional words sticking out from flush-right

[luigi scarso <luigi.scarso@gmail.com>]

On Thu, Mar 4, 2010 at 3:25 PM, James Fisher <jameshfisher@gmail.com> wrote:
> 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.
Today HTML is still crude for a typographer but things can change with WOFF.
You still can't show the potential of ConTeXt  with HTML, because main
output is pdf .

>On the web (which you are), HTML is king.
On a printing house( which I'm) , PDF is the 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.
I grep the code.
It works even offline and in less than 1 second.

> 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.
I disagree.
minimals should be self-cointained.
a documentation system not done in  Context can introduce a useless dependency.

Anyway
even if there is already
http://foundry.supelec.fr/gf/project/modules/scmsvn/
(which is only usefula as testbed, not for documentation)

or if we will have something like cseq one day
(see
http://www.tug.org/utilities/plain/cseq.html, possible made in
automatic fashion from code base)


or a wiki book
(see
http://en.wikibooks.org/wiki/LaTeX
apropos of "Mediawiki is really not the most
appropriate way to document a project" )

it will be not enough --- a good starting point, of course.


In the end, one needs to understand the language, his semantic and
study the code.
With TeXBook, a couple of manuals from pragma (cont-en, metafun) and
the code you are ok
(well also ~1000 pages of pdf specs. are not bad and also  some book
about fonts ...).
Others are articles, and they are ok too.
TeX is a macro language. There are almost ~1000 macros , and maybe
~500 macros in ConTeXt.
Even if we are able to "documents" them in some manner, understanding
them and their relations
is a matter of study the code.


>> About model of development: one developer is not so strange afterall .
>
> 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.

No, not necessarily and not in this situation.
For TeX frozen  means no new features, only  bugfixes;
it means that the language is maintained and backward compatibility is
very important.
(about 80% of scientific articles are in TeX, so backward
compatibility is really important) .
It doesn't mean that the language is perfect.
To me frozen simply says that "it's time to explore the semantic of
the language rather than
add new  features"


>
>>
>> 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.
One developer assure that there is exactly one version e no forks
(friendly or not).
This is also ok because there is no need for forks (afterall none are
thinking to fork LaTeX2e):
> If Hans doesn't
> want to merge someone else's changes to his (authoritative) copy of the
> repo, then
the changes are rejected from the code base.

I'm not saying that a dcvs is useless for documentation or manuals.
But without contributors a dcvs can be practically useless,
and the only contributors for manuals actually are Taco for luatex and
Hans for Context mkiv.




-- 
luigi
___________________________________________________________________________________
If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@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
___________________________________________________________________________________