[TCLCORE] gsoc ideas
Rene Zaumseil
before creating pages on the wiki I would discuss my ideas here.
1. Tcl has a very good documentation, both on the C and the script side.
AFAIK the sources are still in nroff format. And there is also a very
good description on top of each C-function and Tcl-proc.
After I have added tcl support to doxygen it would be possible
to use also information from inside c and script files.
A possible conversion scenario could then:
- convert nroff sources in doxygen sources
- change headers in C files
- change headers in script files
2. With the use of the msgcat package most of tk is multilingual.
Still all of tcl is not. Could and should this be changed?
For reference see:
http://www.tcl.tk/doc/howto/i18n.html#APIs
http://wiki.tcl.tk/1488
http://wiki.tcl.tk/28073
Regards
rene
------------------------------------------------------------------------------
Virtualization & Cloud Management Using Capacity Planning
Cloud computing makes use of virtualization - but cloud computing
also focuses on allowing computing to be delivered as a service.
http://www.accelacomm.com/jaw/sfnl/114/51521223/
_______________________________________________
Tcl-Core mailing list
Tcl-...@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tcl-core
Harald Oehlmann
> 1. Tcl has a very good documentation, both on the C and the script side.
> AFAIK the sources are still in nroff format. And there is also a very
> good description on top of each C-function and Tcl-proc.
>
> - convert nroff sources in doxygen sources
> - change headers in C files
> - change headers in script files
I really like doxygen for source code documentation and it is a good
thing that this is useable for tcl and c.
I suppose that tcldoc should be used for the user documentation.
> 2. With the use of the msgcat package most of tk is multilingual.
> Still all of tcl is not. Could and should this be changed?
Within tcl, this applies only to the error messages.
I prefer english error messages - it is easier to speak about the same
issue on the web etc.
-Harald
Donal K. Fellows
> before creating pages on the wiki I would discuss my ideas here.
Be aware that my message will sound very critical of you in places. It's
not meant to be! I'm just worrying about the quality of tools;
automation doesn't help as much as some believe (given that we're not
doing something dumb like writing lots of HTML by hand!)
> 1. Tcl has a very good documentation, both on the C and the script side.
> AFAIK the sources are still in nroff format. And there is also a very
> good description on top of each C-function and Tcl-proc.
>
> After I have added tcl support to doxygen it would be possible
> to use also information from inside c and script files.
With quite a bit of experience, automatically-generated documentation
tends to be not as nice as properly curated docs. While it is possible
to do things that work well (the documentation for Java is a pretty good
example) most of the time you get people thinking that "oh, it's been
auto-documented so we don't need to do any more work". That's so not
true it's almost funny (but very sad too). One of the key things about
Tcl's documentation is that it now includes not just "this is what these
things do" but also some "this is how you use them" by means of
informative examples; I don't know how easily this would fit with any
doxygen-based system, but I think it is something I would not want to
give up on.
Moreover, the vast majority of code inside Tcl is not part of any public
API as such, and so shouldn't have exposed documentation at all.
> A possible conversion scenario could then:
> - convert nroff sources in doxygen sources
> - change headers in C files
> - change headers in script files
I think you're in danger of documenting the wrong things.
> 2. With the use of the msgcat package most of tk is multilingual.
> Still all of tcl is not. Could and should this be changed?
>
> For reference see:
> http://www.tcl.tk/doc/howto/i18n.html#APIs
> http://wiki.tcl.tk/1488
> http://wiki.tcl.tk/28073
In 8.6 we have been trying to go through all the places where Tcl
generates errors itself and ensure that they all have useful errorCode
lists produced at the same time (as part of making [try] more useful).
It would be valuable if we were to also supply some kind of system
(message catalogs or using them) that would produce human-readable
versions of the messages from them; such catalogs could then have i18n
applied to them. (I'd also like to know of any place where we are not
producing good errorCodes...)
I'm much more reluctant to try to handle the stack traces of errorInfo;
those should not be exposed to users in the first place.
Donal.
Lars Hellström
> Hi all,
>
> before creating pages on the wiki I would discuss my ideas here.
>
> 1. Tcl has a very good documentation, both on the C and the script side.
> AFAIK the sources are still in nroff format. And there is also a very
> good description on top of each C-function and Tcl-proc.
>
> After I have added tcl support to doxygen it would be possible
> to use also information from inside c and script files.
Despite being a habitual practitioner of literal programming, I believe it
would be a step *backwards* to integrate the Tcl manpages with the .c, .h,
and .tcl sources. The reason is that these manpages generally take a high
level view of matters, whereas tightly integrated documentation rather tends
to focus low-level details; much of the information in the manpages have no
obvious corresponding location in the sources, and conversely much of what
should be documented in the sources would simply be noise if put in the
manpage. Moreover, the natural order of doing things in the source file can
be quite different from the natural order of saying things in a manpage;
coupling the two is likely to lead to both becoming less comprehensible.
A thing that I think the manpages could do with is however a review posing
the question of how these manpages are expected to be used. I find myself
using them mostly when I write code using features I'm not fully familiar
with; in other words, I use them in my role as /writer/. Yet the
organisation of in particular the C and Tk manpages (though in different
ways) is rather tailored to a /reader/: if I'm given a piece of code written
by someone else, then I can fairly efficiently figure out what the various
commands and function calls do. If instead (as is more frequently the case)
I want to figure out how to do X, then I'm often forced to randomly browse
manpages in the hope of finding relevant information. And it doesn't help
that the pages often start with several screenfulls of more or less
boilerplate material (standard options of Tk widgets, anyone?) before they
finally get around to saying what the page is actually about. Doing
something about this is however not a task that I would entrust to a GSOCer;
it requires good understanding of all the things that are being documented.
Lars Hellström
Trevor Davel (Twylite)
On 2012/03/08 01:26 PM, Donal K. Fellows wrote:
> On 08/03/2012 08:45, Rene Zaumseil wrote:
>
>
>> 2. With the use of the msgcat package most of tk is multilingual.
>> Still all of tcl is not. Could and should this be changed?
>>
>
> I'm much more reluctant to try to handle the stack traces of
> errorInfo; those should not be exposed to users in the first place.
>
Stack traces should be in the language of the developer, not the user.
I have apps with Russian UIs and Russian error messages, but I'd be
completely unable to support the application if the detailed error log
e-mailed to me was in Russian.
Regards,
Twylite
Larry McVoy
> AFAIK the sources are still in nroff format. And there is also a very
> good description on top of each C-function and Tcl-proc.
I don't understand the desire to move away from nroff. It's not broken,
why fix it?
--
---
Larry McVoy lm at bitmover.com http://www.bitkeeper.com
Lars Hellström
>> 1. Tcl has a very good documentation, both on the C and the script side.
>> AFAIK the sources are still in nroff format. And there is also a very
>> good description on top of each C-function and Tcl-proc.
>
> I don't understand the desire to move away from nroff. It's not broken,
> why fix it?
One reason could be that the number of developers who can maintain
documentation written in nroff is dwindling. It doesn't help that something
isn't broken if hardly anyone understands how to modify it anymore; what
used to be editable source is then effectively becoming an unmodifiable
binary instead.
My experience, coming late to the traditional Unix tools, is:
1. I find it very difficult to read nroff source (despite having mastered
several obscure file formats in my life).
2. I have been unable to find any significant documentation of the format.
3. The only practical way I know of generating working nroff is to use
doctools, converting from .man.
Hence, if someone asked me to modify an nroff manpage in some way, I most
likely wouldn't be able to help. And I suspect I am far from the only one.
Lars Hellström
Brian Griffin
> Larry McVoy skrev 2012-03-08 16.45:
>>> 1. Tcl has a very good documentation, both on the C and the script side.
>>> AFAIK the sources are still in nroff format. And there is also a very
>>> good description on top of each C-function and Tcl-proc.
>>
>> I don't understand the desire to move away from nroff. It's not broken,
>> why fix it?
>
> One reason could be that the number of developers who can maintain
> documentation written in nroff is dwindling. It doesn't help that something
> isn't broken if hardly anyone understands how to modify it anymore; what
> used to be editable source is then effectively becoming an unmodifiable
> binary instead.
>
> My experience, coming late to the traditional Unix tools, is:
> 1. I find it very difficult to read nroff source (despite having mastered
> several obscure file formats in my life).
> 2. I have been unable to find any significant documentation of the format.
> 3. The only practical way I know of generating working nroff is to use
> doctools, converting from .man.
> Hence, if someone asked me to modify an nroff manpage in some way, I most
> likely wouldn't be able to help. And I suspect I am far from the only one.
>
> Lars Hellström
What he said summarized in a one word answer to the question "what's broken?": Authoring.
-Brian
Joe English
Lars_Hellstrom wrote:
> Larry McVoy wrote:
> > I don't understand the desire to move away from nroff. It's not broken,
> > why fix it?
>
> One reason could be that the number of developers who can maintain
> documentation written in nroff is dwindling. It doesn't help that something
> isn't broken if hardly anyone understands how to modify it anymore; what
> used to be editable source is then effectively becoming an unmodifiable
> binary instead.
>
> My experience, coming late to the traditional Unix tools, is:
> 1. I find it very difficult to read nroff source (despite having mastered
> several obscure file formats in my life).
> 2. I have been unable to find any significant documentation of the format.
That's historically been a real problem. (For many years,
most Unices came equipped with nroff(1), since man(1) uses it,
but unless you paid big $$$ for the "Documenter's Workbench"
you didn't get any documentation at all on the file format!)
Fortunately most of the original documentation has been liberated:
see <URL: http://troff.org/papers.html >. Joe Ossanna's
reference manual (CSTR#54) is quite good.
The Heirloom Project has revised and updated documentation
for the DWB toolchain as well:
<URL: http://heirloom.sourceforge.net/doctools.html >
Lastly, the groff manual (which, somewhat ironically,
is in GNU Info format) is also decent (though IMO it
suffers from the typical GNU problem where it reads like
it wants to be a novel instead of a reference manual..)
Troff, much like vi, is actually rather straightforward
and can be pleasant to use once you get the basic principles.
(And, much like vi, if the basic principles *haven't* been
explained, it's a nightmare. Come to think of it, the
same applies to Tcl...)
--Joe English
Rene Zaumseil
> On 08/03/2012 08:45, Rene Zaumseil wrote:
> > before creating pages on the wiki I would discuss my ideas here.
>
> Be aware that my message will sound very critical of you in places. It's
> not meant to be! I'm just worrying about the quality of tools;
> automation doesn't help as much as some believe (given that we're not
> doing something dumb like writing lots of HTML by hand!)
of the people doing the real work.
>
> > 1. Tcl has a very good documentation, both on the C and the script side.
> >
> > AFAIK the sources are still in nroff format. And there is also a very
> > good description on top of each C-function and Tcl-proc.
> >
> > After I have added tcl support to doxygen it would be possible
> > to use also information from inside c and script files.
>
> With quite a bit of experience, automatically-generated documentation
> tends to be not as nice as properly curated docs. While it is possible
> to do things that work well (the documentation for Java is a pretty good
> example) most of the time you get people thinking that "oh, it's been
> auto-documented so we don't need to do any more work". That's so not
> true it's almost funny (but very sad too). One of the key things about
> Tcl's documentation is that it now includes not just "this is what these
> things do" but also some "this is how you use them" by means of
> informative examples; I don't know how easily this would fit with any
> doxygen-based system, but I think it is something I would not want to
> give up on.
>
> Moreover, the vast majority of code inside Tcl is not part of any public
> API as such, and so shouldn't have exposed documentation at all.
>
> > A possible conversion scenario could then:
> > - convert nroff sources in doxygen sources
> > - change headers in C files
> > - change headers in script files
>
> I think you're in danger of documenting the wrong things.
no try to push this idea further.
>
> > 2. With the use of the msgcat package most of tk is multilingual.
> >
> > Still all of tcl is not. Could and should this be changed?
> >
> > For reference see:
> > http://www.tcl.tk/doc/howto/i18n.html#APIs
> > http://wiki.tcl.tk/1488
> > http://wiki.tcl.tk/28073
>
> In 8.6 we have been trying to go through all the places where Tcl
> generates errors itself and ensure that they all have useful errorCode
> lists produced at the same time (as part of making [try] more useful).
> It would be valuable if we were to also supply some kind of system
> (message catalogs or using them) that would produce human-readable
> versions of the messages from them; such catalogs could then have i18n
> applied to them. (I'd also like to know of any place where we are not
> producing good errorCodes...)
>
> I'm much more reluctant to try to handle the stack traces of errorInfo;
> those should not be exposed to users in the first place.
Rene
Stuart Cassoff
Stuart Cassoff
it's too much overhead for the Tcl distro.
Stu
On 03/08/12 13:37, Stuart Cassoff wrote:
> What about mandoc?
> http://en.wikipedia.org/wiki/Mandoc
> Stu
Jeff Hobbs
I for one never found nroff source docs hard to read or write, but then
again the autoconf didn't scare me much either (it was more of a
puzzling challenge ;) ). However, the one real limitation I found is
that it can't handle screenshots. This makes Tk docs much less
friendly. In the same manner that adding examples to the Tcl docs was a
real boon for the user, we've never been able to pictorialize for Tk.
I'd be up for switching to a doc format that could manage that well.
Maybe the rest format would satisfy?
Jeff
Larry McVoy
> that it can't handle screenshots. This makes Tk docs much less
> friendly. In the same manner that adding examples to the Tcl docs was a
> real boon for the user, we've never been able to pictorialize for Tk.
>
> I'd be up for switching to a doc format that could manage that well.
> Maybe the rest format would satisfy?
groff can handle screenshots just fine but people seem to have a tough time
with that.
What about pod? I whipped up a somewhat pod compat tool in L (which runs
on tcl) that produces stuff like this:
http://www.mcvoy.com/lm/L/l.html
input was this:
http://www.mcvoy.com/lm/L/l.pod
--
---
Larry McVoy lm at bitmover.com http://www.bitkeeper.com
------------------------------------------------------------------------------
sigzero
> However, the one real limitation I found is
> that it can't handle screenshots. This makes Tk docs much less
> friendly. In the same manner that adding examples to the Tcl docs was a
> real boon for the user, we've never been able to pictorialize for Tk.
>
> I'd be up for switching to a doc format that could manage that well.
> Maybe the rest format would satisfy?
groff can handle screenshots just fine but people seem to have a tough time
with that.
What about pod? I whipped up a somewhat pod compat tool in L (which runs
on tcl) that produces stuff like this:
http://www.mcvoy.com/lm/L/l.html
input was this:
http://www.mcvoy.com/lm/L/l.pod
Bob
Larry McVoy
> On 09/03/2012, at 5:27 AM, Larry McVoy wrote:
>
> >> However, the one real limitation I found is
> >> that it can't handle screenshots. This makes Tk docs much less
> >> friendly. In the same manner that adding examples to the Tcl docs was a
> >> real boon for the user, we've never been able to pictorialize for Tk.
> >>
> >> I'd be up for switching to a doc format that could manage that well.
> >> Maybe the rest format would satisfy?
> >
> > groff can handle screenshots just fine but people seem to have a tough time
> > with that.
> >
> > What about pod? I whipped up a somewhat pod compat tool in L (which runs
> > on tcl) that produces stuff like this:
> >
> > http://www.mcvoy.com/lm/L/l.html
> >
> > input was this:
> >
> > http://www.mcvoy.com/lm/L/l.pod
>
>
> http://jim.tcl.tk/fossil/doc/trunk/Tcl_shipped.html
>
> generated from:
>
> http://jim.tcl.tk/fossil/doc/trunk/jim_tcl.txt
The bummer is that you have to do the index in that format, or at least
that's how your example came. Pod can generate that for you automagically,
at least mine can.
Larry McVoy
> that's how your example came. Pod can generate that for you automagically,
> at least mine can.
For example:
http://www.mcvoy.com/lm/nested/L.html
Larry McVoy
> > The bummer is that you have to do the index in that format, or at least
> > that's how your example came. Pod can generate that for you automagically,
> > at least mine can.
>
> For example:
>
> http://www.mcvoy.com/lm/nested/L.html
and
http://www.mcvoy.com/lm/nested/nested.html
Steve Bennett
> On Thu, Mar 08, 2012 at 12:26:35PM -0800, Larry McVoy wrote:
>>> The bummer is that you have to do the index in that format, or at least
>>> that's how your example came. Pod can generate that for you automagically,
>>> at least mine can.
>>
>> For example:
>>
>> http://www.mcvoy.com/lm/nested/L.html
>
> and
>
> http://www.mcvoy.com/lm/nested/nested.html
Yes, that's nice.
--
µWeb: Embedded Web Framework - http://uweb.workware.net.au/
WorkWare Systems Pty Ltd
W: www.workware.net.au P: +61 434 921 300
E: ste...@workware.net.au F: +61 7 3391 6002
Steve Bennett
>> However, the one real limitation I found is
>> that it can't handle screenshots. This makes Tk docs much less
>> friendly. In the same manner that adding examples to the Tcl docs was a
>> real boon for the user, we've never been able to pictorialize for Tk.
>>
>> I'd be up for switching to a doc format that could manage that well.
>> Maybe the rest format would satisfy?
>
> groff can handle screenshots just fine but people seem to have a tough time
> with that.
>
> What about pod? I whipped up a somewhat pod compat tool in L (which runs
> on tcl) that produces stuff like this:
>
> http://www.mcvoy.com/lm/L/l.html
>
> input was this:
>
> http://www.mcvoy.com/lm/L/l.pod
asciidoc is another option.
http://jim.tcl.tk/fossil/doc/trunk/Tcl_shipped.html
generated from:
http://jim.tcl.tk/fossil/doc/trunk/jim_tcl.txt
Cheers,
Steve
--
µWeb: Embedded Web Framework - http://uweb.workware.net.au/
WorkWare Systems Pty Ltd
W: www.workware.net.au P: +61 434 921 300
E: ste...@workware.net.au F: +61 7 3391 6002
Michael Schlenker
Adding to the me too answers.
Sphinx (http://sphinx.pocoo.org/) also produces quite some nice results.
Just using it for some move away from docbook at work.
One could define a ReST role for Tcl constructs and stuff.
But on the other hand, its needs a ton of Python dependencies...
Michael
Donal K. Fellows
> 2. I have been unable to find any significant documentation of the format.
You're looking for a copy of CSTR #54, the Troff User's Manual (I did
some research on this a few years ago when I was revising the code that
converts our *roff to html). When I google for "cstr 54", the second hit
is a postscript copy; I assume that'll be good enough for you.
When rendering for yourself, use groff. Be aware that Tcl actually uses
a very stylized subset of *roff (plus a few of our own macros) that is
far more regular than most other uses out there in the wild. It's
actually *easier* by copying the style of what is already there because
it is such a rigid style. (Yes, I do go through and audit the style from
time to time...) If you have questions, ask here.
Donal.
Larry McVoy
>
> > http://www.mcvoy.com/lm/L/l.html
> >
> > input was this:
> >
> > http://www.mcvoy.com/lm/L/l.pod
> >
> > POD is a great one. It has served Perl very well.
>
> Adding to the me too answers.
>
> Sphinx (http://sphinx.pocoo.org/) also produces quite some nice results.
> Just using it for some move away from docbook at work.
>
> One could define a ReST role for Tcl constructs and stuff.
>
> But on the other hand, its needs a ton of Python dependencies...
Blech. The L code that rendered the examples above is here:
http://www.mcvoy.com/lm/L/L.html#pod2html.l
It's not very much and depends only on Tcl+L. Someone could rewrite that
in about 20 minutes in pure tcl.
--
---
Larry McVoy lm at bitmover.com http://www.bitkeeper.com
------------------------------------------------------------------------------
Donal K. Fellows
>> However, the one real limitation I found is
>> that it can't handle screenshots. This makes Tk docs much less
>> friendly. In the same manner that adding examples to the Tcl docs was a
>> real boon for the user, we've never been able to pictorialize for Tk.
>>
>> I'd be up for switching to a doc format that could manage that well.
>> Maybe the rest format would satisfy?
>
> groff can handle screenshots just fine but people seem to have a tough time
> with that.
I totally agree with Jeff that Tk wants screenshots. It's just awkward
to actually get there. We can solve for printed docs and HTML (modulo
the complexity with different rendering formats) but 'man' just can't
due to being limited to a terminal. We'd have to do a link and… well,
it's starting to get complicated. :-(
Donal.
Larry McVoy
>
> Donal.
I suspect that you, like me, are hanging on to troff a bit too much.
Personally, I *love* roff with a good macro package, the input can
product text and high quality printed (and w/ groff, it can produce html)
and the input version controls extremely well because of the markups
forcing line breaks.
That said, people want their docs on the web these days, and the web
lets you do screen shots nicely.
If someone wants to convert all the docs to POD format and the core
finds that to be pleasant, I could get behind that, maybe even help.
Bernard Desgraupes
Le 8 mars 12 à 21:21, Steve Bennett a écrit :
> On 09/03/2012, at 5:27 AM, Larry McVoy wrote:
>
>>> However, the one real limitation I found is
>>> that it can't handle screenshots. This makes Tk docs much less
>>> friendly. In the same manner that adding examples to the Tcl docs
>>> was a
>>> real boon for the user, we've never been able to pictorialize for
>>> Tk.
>>>
>>> I'd be up for switching to a doc format that could manage that well.
>>> Maybe the rest format would satisfy?
>>
>> groff can handle screenshots just fine but people seem to have a
>> tough time
>> with that.
>>
>> What about pod? I whipped up a somewhat pod compat tool in L
>> (which runs
>> on tcl) that produces stuff like this:
>>
>> http://www.mcvoy.com/lm/L/l.html
>>
>> input was this:
>>
>> http://www.mcvoy.com/lm/L/l.pod
>
> asciidoc is another option.
>
> http://jim.tcl.tk/fossil/doc/trunk/Tcl_shipped.html
>
> generated from:
>
> http://jim.tcl.tk/fossil/doc/trunk/jim_tcl.txt
>
You might have a look at Aida: it defines a markup language which
supports images and can convert to HTML, LaTeX, man, hyperref, many
wiki syntaxes (Trac, Mediawiki, pmwiki), etc.
It generates toc and index automagically. It is also extensible: the
'aida' command line tool embeds a Tcl interpreter and conversion is
based on callbacks written in pure Tcl.
See
http://aidadoc.sourceforge.net/index.html
and the documentation here:
http://aidadoc.sourceforge.net/AidaHelp.html
cheers,
Bernard
Rene Zaumseil
Hi,
regarding the features doxygen is still in the run.
Some output formats: latex, pdf, rtf, manpage, html, xml
For a list of features see http://www.stack.nl/~dimitri/doxygen/features.html
On the other hand a nice little tcl-only solution keeps the
dependencies low.
Regards,
rene
Frédéric Bonnet
especially liked asciidoc), I personally use NaturalDocs for my Colibri
project. I chose this package (depends on perl but installs easily)
instead of doxygen for source-based doc generation because it allows for
free-form text within C docs (it also supports Tcl), in a way that is
very close to what Tcl currently uses. It's so close that when I started
the project I used the Tcl format, and moving to NaturalDocs only
involved a simple conversion script.
For example, in Tcl style you'll have:
/*
*----------------------------------------------------------------------
*
* Col_SetErrorProc --
*
* Set or reset the thread's custom error proc.
*
* Results:
* None.
*
* Side effects:
*
*----------------------------------------------------------------------
*/
void
Col_SetErrorProc(
Col_ErrorProc *proc) /* The new error proc (may be NULL). */
{
(...)
In NaturalDocs you'll have:
/*
*----------------------------------------------------------------------
*
* Function: Col_SetErrorProc
*
* Set or reset the thread's custom error proc.
*
* Arguments:
* proc - The new error proc (may be NULL).
*
* Results:
* None.
*
* Side effects:
*
*----------------------------------------------------------------------
*/
void
Col_SetErrorProc(
Col_ErrorProc *proc)
{
(...)
The major difference is the way arguments are declared (Tcl style uses
inline comments in the arg list).
There are nice features such as user-defined headers (just write the
header title ended by a colon) and topic keywords. I've used this
feature to differentiate public vs. internal stuff. E.g. public
functions are defined like this:
/*---------------------------------------------------------------------------
* Function: Col_NewRopeFromString
*
(...)
Whereas internal functions are like:
/*---------------------------------------------------------------------------
* Internal Function: FindCharProc
*
(...)
Another nice feature is the possibility to strip prefixes off index
lists, so that e.g. Tcl_Object will be under 'O' and not 'T'. See:
http://www.naturaldocs.org/customizinglanguages.html#IndexPrefixes
Else, it supports cross-linking, custom indexes, tables, images, etc.
Regarding man page generations, we could define a custom topic keyword
such as "Manual" and write man pages in the source code, then select
which keywords to extract for internal, public API, and man page
generation in order to generate distinct sets of documentation. See:
http://www.naturaldocs.org/customizingtopics.html
An alternative would be to leverage the Wiki formatter so that
documentation is written in Wiki style and extracted from the source
code. This could give interesting features such as single-file
documentation in a Wikit. That way we have a pure Tcl solution but we
risk reinventing the wheel in the process given the number of quality
doc generators out there.
Joe English
Amidst all the suggestions for alternate documentation formats,
I think the question first needs to be asked:
Do we really want to migrate from nroff -man?
Speaking personally, my answer is "No, not really."
Although nowadays I mostly use a Web browser to RTFM,
it's still nice to have `:!man 3tcl Whatever` at my
fingertips for those times when I just need a quick
memory refresh. I wouldn't *totally* hate to lose
that, but it'd be missed.
And if the consensus is "Yeah, we should switch",
there are other, possibly more important, issues
than "what should we switch to?"
First is converting the existing documentation,
preserving as much semantic information as possible.
This is nontrivial. (I speak from experience here).
Even if ${tool_of_your_choice} comes with a `man2myformat`
automagic converter, don't expect it to work: unless
"man2myformat" was developed with Tcl and Tk manpages
specifically in mind, it *will* lose information.
Then there's the toolchain. A big chunk of Tcl's tools/*
infrastructure is dedicated to dealing with the manpages;
that'd all have to be updated. Don't know how big a task
that would be. DKF, the ActiveStaters, and downstream
packagers are probably the main stakeholders here.
--Joe English
Donal K. Fellows
> Do we really want to migrate from nroff -man?
>
> Speaking personally, my answer is "No, not really."
>
> Although nowadays I mostly use a Web browser to RTFM, it's still nice
> to have `:!man 3tcl Whatever` at my fingertips for those times when I
> just need a quick memory refresh. I wouldn't *totally* hate to lose
> that, but it'd be missed.
I agree. I definitely use it when I want to look things up. Especially
when I'm offline (quite a bit of each day). It's a shame I can't see an
image in a normal terminal, but there's a limit to some things. :-)
> And if the consensus is "Yeah, we should switch", there are other,
> possibly more important, issues than "what should we switch to?"
>
> First is converting the existing documentation, preserving as much
> semantic information as possible. This is nontrivial. (I speak from
> experience here). Even if ${tool_of_your_choice} comes with a
> `man2myformat` automagic converter, don't expect it to work: unless
> "man2myformat" was developed with Tcl and Tk manpages specifically in
> mind, it *will* lose information.
Some of that will be because the information wasn't really there in the
first place; it was only convention, not actual information. Still, our
use of the *roff format is extremely stereotypical (especially in 8.6,
where things are cleaner than they've been for at least a decade) so it
would be possible to recover with enough work.
But I don't really fancy doing lots of work just to stand still. That's
a little too close to how my day-job feels sometimes.
> Then there's the toolchain. A big chunk of Tcl's tools/*
> infrastructure is dedicated to dealing with the manpages; that'd all
> have to be updated. Don't know how big a task that would be. DKF, the
> ActiveStaters, and downstream packagers are probably the main
> stakeholders here.
The most serious suggestion to date was doctools, which is really just a
more Tcl-like wrapper round the style of *roff we use (and which can
also target other formats directly). The problem is that it's not quite
precisely the same output; there are some awkward edge cases when
working with a documentation-set as complex as Tcl's. (I remember
experimenting and finding could do the 95% conversion easily, but 100%
wasn't attainable at the time. It's a good few years ago though, so I
don't remember where things came unstuck; all I remember for sure is
that I was using namespace(n) as a test case.)
Our current Tcl*roff -> HTML converter produces nicer output than
doctools does (in particular, with denser cross-links; important because
they greatly boost the value of the documentation).
As noted above, I'm not very keen on rewriting the converter code again.
Yet for all that, I'm significantly less keen on reducing the quality of
documentation as experienced by users, and I feel that the key two cases
are 1) what you get with 'man', and 2) what you get on the web (which I
understand the documentation for Windows to be based on these days). Are
there other cases which need to be addressed?
Donal.
Larry McVoy
> Our current Tcl*roff -> HTML converter produces nicer output than
> doctools does (in particular, with denser cross-links; important because
> they greatly boost the value of the documentation).
Are these maintained online someplace?
If this is an example, seems broken, check out the lack of links:
http://tmml.sourceforge.net/doc/tcl/lreverse.html
As for what is not served by the current system, tk man pages really really
want screen shots. For tcl man pages, I whole heartedly support leaving
them in roff (if the html can get fixed).
--
---
Larry McVoy lm at bitmover.com http://www.bitkeeper.com
------------------------------------------------------------------------------
Michael Schlenker
Am 10.03.2012 um 16:20 schrieb Larry McVoy:
> On Sat, Mar 10, 2012 at 06:36:32AM +0000, Donal K. Fellows wrote:
>> Our current Tcl*roff -> HTML converter produces nicer output than
>> doctools does (in particular, with denser cross-links; important because
>> they greatly boost the value of the documentation).
>
> Are these maintained online someplace?
>
> If this is an example, seems broken, check out the lack of links:
>
> http://tmml.sourceforge.net/doc/tcl/lreverse.html
>
> As for what is not served by the current system, tk man pages really really
> want screen shots.
Would it be a good idea to improve the tkdocs.com website some more, so one could point to
it for nice screenshots and more than reference documentation for tk?
Michael
Joe English
Larry McVoy wrote:
> Donal K. Fellows wrote:
> > Our current Tcl*roff -> HTML converter produces nicer output than
> > doctools does (in particular, with denser cross-links; important because
> > they greatly boost the value of the documentation).
>
> Are these maintained online someplace?
Yes: the main site is:
<URL: http://www.tcl.tk/doc/ >
<URL: http://www.tcl.tk/man/tcl8.6/ >
> If this is an example, seems broken, check out the lack of links:
>
> http://tmml.sourceforge.net/doc/tcl/lreverse.html
That's the output of a different converter, which doesn't
really get much active maintenance. (I ought to just take
the whole TMML project offline, but a few people have said
they still find the output useful...)
Hadn't noticed the broken SEE ALSO links, those should be
mostly fixed now.
--Joe
Donal K. Fellows
> I totally agree with Jeff that Tk wants screenshots. It's just awkward
> to actually get there. We can solve for printed docs and HTML (modulo
> the complexity with different rendering formats) but 'man' just can't
> due to being limited to a terminal. We'd have to do a link and… well,
> it's starting to get complicated. :-(
Further to this, I've posted the start of a macro definition for figures
on the dkf-documentation-figures branch. It's rather experimental (and
missing some actual figures to test with) but does appear to work in
groff (in both -Tutf8 and -Tps modes; I anticipate it will work with
classic nroff too, and in many other groff modes, but not classic troff
unless it understands the .PSPIC macro). The HTML converter is drafted,
but untested.
Example of use (which would have to start in the first column):
.FI buttonWin "How Tk displays a button on Windows."
That will produce a link to a PNG image we'll put on www.tcl.tk _or_ use
either img/buttonWin.eps or a <img src=...> to actually render the image
as part of the docs directly. It also places the caption ("How Tk ..."
above) underneath. It's probably wise to keep the length of captions
small, and there's no support yet for building a list of figures. I
doubt I'll ever bother with that. :-)
Donal.
Mo DeJong
cheers
Mo DeJong
Andreas Kupries
To all, generally, please do not forgot to add your gsoc ideas to
Possibly check if the idea existed in previous years as well, and simply move
it forward.
On 3/12/2012 12:49 PM, Mo DeJong wrote:
> A Tcl project that is long overdue would be to create a new build system
> for Tcl and Extensions based on LLVM. This would make it possible to build
> both Tcl and any Extensions with a single compiler on any system that already
> supports LLVM. The problems related to building binary extensions and Tcl
> itself can be significantly simplified by choosing just one compiler to
> support (clang or gcc). I would not be able to manage said project, but I
> would like to pitch in and help get it off the ground if folks are interested.
Can you clarify for us a bit ?
* Are you talking (roughly) about a replacement for tcl.m4 which knows
only about llvm/clang/gcc, simplifying the configure
Maybe even a whole-sale replacement for TEA ?
* Or about a Tcl extension which binds to the llvm libraries, making the
compiler infrastructure available from within Tcl ?
(http://wiki.tcl.tk/26308)
> http://llvm.org/
>
> cheers
> Mo DeJong
--
Andreas Kupries
Senior Tcl Developer
Code to Cloud: Smarter, Safer, Faster™
P: 778.786.1122
F: 778.786.1133
andr...@activestate.com
http://www.activestate.com
Learn about Stackato for Private PaaS: http://www.activestate.com/stackato
http://www.eurotcl.tcl3d.org/ - EuroTcl 2012, July 7-8 , Munich, Germany.
http://www.tcl.tk/community/tcl2012/ - Tcl'2012, Nov 12-16, Chicago, IL, USA.