Re: [Tcllib-devel] Questions about writting the docs and selenium-tcl

[Andreas K. <and...@ac...>]

On Tue, May 26, 2015 at 3:52 PM, Miguel <apl...@gm...> wrote:
> Hi Andreas,
>
> then the convention in tcllib is to use 4 spaces instead of tabs. Is this
> convention standard in Tcl?

Yes.

> In other words, Is this convention recommended
> in the Tcl style guide?

AFAIK yes.

> What is the preferred editor for Tcl? I am using Geany, tkcon and ezdit
> (this last editor is very well written and it use TclOO).

(1) I do not really care as long as the output is suitable.

(2) I am myself mostly an emacs person, mainly because it was the most
common editor when I started CS works, in the 90's. Never bothered to
change. Do not take this as a request to change yourself. See (1).


> I also use geany for python.
>
> Where can I find documentation about the syntax used in the files *.man?

The introduction to the format is at
https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/doctools/doctools_lang_intro.html
It contains links to the syntax- and command-references.

> How can I convert these files to html?

In the toplevel directory of a Tcllib checkout you can run

  % ./sak.tcl doc validate modules/yaml ; # - validation, no output

to validate that the input files are correct (for that module).

  % ./sak.tcl localdoc

regenerates the embedded documentation under embedded/ (nroff and html).
For additional forms see

  % ./sak.tcl help doc

> I want to change huddle.man.
>
> Perhaps the documentation of json2huddle can also be included in huddle.man
> because there is only one proc. What do you think?

Actual the question is, do you want 'json2huddle.tcl' to provide a
separate package for this conversion command ?
If yes, then this package must have its own documentation file.

If you want the conversion functionality as part of the huddle
package, then the documentation of the command must be in the
documentation for huddle, and the code should either be sourced from
huddle.tcl, or placed into huddle.tcl

In other words, your choices regarding the organization of the code
drive the organization of the documentation.

> It also seems that there is no standard way to generate automatically
> documentation from the source code.

That is true. There are Tcl-based tools around, but not a standard one.
See
  * tcldoc - http://wiki.tcl.tk/5598
  * autodoc - http://wiki.tcl.tk/2799 (myself, old)
  * tdoc - http://wiki.tcl.tk/7577

Doxygen (http://wiki.tcl.tk/17438) seems to be a general standard, and
is able to parse Tcl code.

> Is there some library with respect to this in tcllib?

No.

>
> I can see the "diffs" of changes from one revision to other. But how can I
> download the source code with all the new changes applied? For example, If I
> go to the leaf revision:
>     https://core.tcl.tk/tcllib/info/0bb3131985e8efdc
>
> Where I have to click to download the source code with the new changes?

Go through the
    https://core.tcl.tk/tcllib/login link
to log in as "anonymous" (with the shown password), then go to the /info page.
You should then see tarball and zip links to get the specific revision.

> If I click on "ZIP archive" in the Downloads section, I download a code but
> with no change applied. ( I am revising the code in yaml directory)

The download section is specifically set up for the releases and
snapshot from the trunk head. The huddle work is currently done on a
branch.

> I attach to this email the new selenium library.

I will respond to that part in a separate mail.

-- 
% Tcl'2015 Oct 19-23 = http://www.tcl.tk/community/tcl2015/cfp.html
% EuroTcl'15 June 20-21 = http://www.eurotcl.tcl3d.org/
Andreas Kupries
Senior Tcl Developer
Code to Cloud: Smarter, Safer, Faster™
F: 778.786.1133
and...@ac..., http://www.activestate.com
Learn about Stackato for Private PaaS: http://www.activestate.com/stackato