Work at SourceForge, help us to make it a better place! We have an immediate need for a Support Technician in our San Francisco or Denver office.

Close

#928 html - documentation, examples needed

closed-fixed
nobody
html (18)
5
2007-08-21
2007-06-20
No

The documentation for the html package has some errors and typographical errors.

The synopsis lists the procedures in not quite alphabetical order. The init procedure appears between refresh and row.

The explanation for ::html::cell uses upper case tags whereas lower case tags are really used.

The explanation for ::html::openTag lists the arguments as "tags args" when the code uses "tags param". Using multiple args (implied by args) will fail.

::html::row should say that it does NOT used defaults for the td tag as defined in the ::html::init call.

Examples would be very instructive.

Discussion

    • labels: --> html
    • assigned_to: nobody --> andreas_kupries
     
  • Logged In: YES
    user_id=75003
    Originator: NO

    Synopsis lists commands in the order they are listed in the manpage body. Actually doctools hasn't specified any type of order for the sysnopis ... I.e. this is an undocumented implementation detail ... Fixed order in the body.

    Capitalization ... Apparently most explanations use uppercase tag names. See html::bodyTag, checkbox, checkSet, etc. I guess it is simply a kind of markup. ... Changing to lowercase now, and using 'term' as markup for tags, i.e. relatively general semantics. ... Done.

    openTag ... Worse, the param argument is even optional and not documented as such. It is actually not documented at all. Fixed.

    row ... done.

    Examples ... I haven't written this module and don't really know how to use it, therefore I am not really suited to writing examples.

    I am leaving this report open, with modified summary, unassigned, for whoever is able to provide examples.

     
    • assigned_to: andreas_kupries --> nobody
    • summary: docummentation errors in html package --> html - documentation, examples needed
     
  • Logged In: YES
    user_id=69099
    Originator: YES

    I also noticed this. The explanation for title says: ::html::title title
    Side effect only. Call this before ::html::head to define the TITLE for a page.

    This is incorrect. ::html::title is called by ::html::head; calling ::html::title before calling ::html::head would have no effect. Calling ::html::title after callilng ::html::title would change the result of calling ::html::getTitle, but it does not affect the title of the page.

     
  • Logged In: YES
    user_id=69099
    Originator: YES

    A couple more clarifications.

    tableFromArray creates a two-column table with a heading that matches the array name, and each row containing a name, value pair. The array names are sorted by lsort before use.

    tableFromList creates a two-column table from a nonempty, with each row containing a label, value pair.

     
  • Logged In: YES
    user_id=69099
    Originator: YES

    The following procedures exist in html.tcl but are not documented: css, doctype, js, tagParam, urlParent.

    The following procedures are not listed in alphabetical order: init, minorList, paramRow, set.
    This makes their documentation harder to find.

     
  • Logged In: YES
    user_id=75003
    Originator: NO

    Going through the accumulated comments

    html::title - Are you saying the documentation is wrong, that the behaviour of the package is wrong, or both ? From the description you give it seems to me that the documentation may be right, and actual behaviour wrong. However, not being the author, I am not really sure. Should the behaviour be wrong then this should be submitted as a separate bug.

    TableFromArray/List - I am guessing that you are asking me to extend the documentation for them, based on the described behaviour ?

    Undocumented procedures - I do not know what they do either. Can you draw up some documentation for them for me, and attach to this bug ?

    Sorting minorList, paramRow, etc. - I sorted these yesterday, see my first comment 'Fixed order in the body.'

     
  • Logged In: YES
    user_id=69099
    Originator: YES

    html::title documentation is wrong. It's used inside the package, but having the user call it makes no sense since it's called by html::head where the title is required anyway.

    Yes, I think the real behavior of tableFromArray/List should be documented.

    I can try to infer documentation to the undocumented procedures.

    I wasn't sure if you fixed all the sorting problems.

    I've been thinking of making a different version of this that would allow creation of more than one stack. I might if I can find the time.

     
  • Logged In: YES
    user_id=75003
    Originator: NO

    tableFrom{Array,List} documentation extended. html::title documentation disabled (effectively removed from output, still in the .man, as comment). Committed. When documentation for the undocumented commands comes in this bug can be re-opened, or a new bug made.

     
    • status: open --> closed-fixed