MonthOctober 2006

Chili 1.0_b Released Today

UPDATE: Chili 1.1 has been released

Changes

  • No code change.
  • A proper free license (MIT) has been added to all files.
  • The version number has been added to the path of the Chili site.
  • A new directory structure for examples has been added, together with a brand new example where Chili highlights jQuery.

Files

  • all
  • manual
  • Chili highlighting Chili
  • Chili highlighting jQuery

Free license
I clearly stated the terms of the license in the release post. But it’s important that any sensible information be protected by the same terms, so I added an MIT license to them.

Versioned directories
I found that without version numbers in the path I had to make adjustments to incoming links or provide some kind of redirection. Versioned directories should save me time.

  • Content previously found in /aercolino /chili/ has been moved to /aercolino /chili /1.0/
  • Content of this 1.0_b release has been placed in /aercolino /chili /1.0_b/

Examples
Starting from /aercolino /chili /1.0_b /examples/ can now be found a new directory structure for showing how Chili can be used in a sample environment. The base directory hosts generic files linked by the examples, like recipes and stylesheets.

chili-1.0.js has been configured for accessing recipes and stylesheets from this directory. Then it has been packed with the Dean Edwards’ wonderful JavaScript compressor. But it’s not been deleted, for leaving a configuration reminder and for being able to adjust it in the future.

Any example has its own directory numbered from 1 upward, like /aercolino /chili /1.0_b /examples /1 /chili-1.0-highlighting-chili-1.0.html which is the example previously available.

Chili highlighting Chili

/aercolino /chili /1.0_b /examples /1 /chili-1.0-highlighting-chili-1.0.html is the only file in its directory. It loads all the files it needs from its parent directory. This is how highlighting should generally work. With Chili there is the additional benefit that the example only links to jquery and chili. Chili itself will automatically load any file it needs.

Chili highlighting jQuery

/aercolino /chili /1.0_b /examples /2 /chili-1.0-highlighting-jquery-1.0.2.html is not the only file in its directory. This is for showing how to deal with exceptions to the general plan. This example highlights the jQuery script by marking up JavaScript and jQuery items. So special jQuery-flavored JavaScript recipe and stylesheet need to be used.

Chili 1.0 Released Today

UPDATE: Chili 1.0_b has been released

Features

  • Syntax highlighting for the browser; IE, Firefox, Mozilla, and Opera friendly
  • a jQuery, AJAX, Javascript, fully documented, free application
  • Javascript and Lotusscript recipes provided
  • 100% compatible with Code Highlighter 0.4 styleSets

Files

  • chili1.0-example.html
  • chili1.0-manual.txt
  • chili1.0-all.zip

This software is gratis.
You could buy me a cappuccino, but it’s up to you.

Comments about XGC

If you want to comment about the XGC website, please post here.

jQuery: API documentation /3

Still about improving the official documentation.
|modified content, my style – snapshot for jQuery $( String, Object )
|official content, my style – snapshot for jQuery $( String, Object )
|official content & stylesnapshot for jQuery $( String, Object )

Examples on a common ground
The use cases in a software documentation are very important. And as a general principle, the more they are standardized around some basic concepts, the more useful they are, because the reader can easily tell the differences and concentrate on them. As much as possible the differences should be limited to what is special about the functionality being described.

  1. An examples element in the documentation XML has 5 (sub)elements: desc, code, comment, before, after. The answer to why I added the comment element is given below.
  2. The labels for an example subelements (as they now appear in my working sample) are: Example, Solution, Comment, Before, and After (respectively)
  3. Example must be a description of a problem to solve, and I chose to begin it with a “To” + infinitive form, because this is the standard for problems at school; it’s not required that the functionality be central to it. A real and bigger example is preferable to a shorter but artificial one. The same example used over and over, either for showing different solutions or different functionalities should be good, because of the standard effect. Different solutions should be referenced one from the others.
  4. Solution must be limited to the jQuery code excerpt that solves the problem; and it should be complete, so that it could be introduced in the usual framework as is, and produce the After when applied to the Before
  5. Comment can be anything worth to note about the Solution, and the other elements. Less noise, the better. However this is the preferred space for all that is not strictly a problem or solution description. Really the Comment exists for segregating the talk from the data.
  6. Before must be the test context to which the solution is applied, better if represented by a meaningful HTML excerpt.
  7. After must be the Before context as changed by the application of the solution, better if represented by a meaningful HTML excerpt.
  8. Before and After should work together, and the result of their comparison should look like a diff result.
  9. Before and After should also provide context for themselves. That is, <div></div> seems a good choice for a Before but it’s not, beacuse it has no clear context. In fact <body><div></div></body> is much better, because the reader now knows the DOM completely and can make safe assumptions
  10. In general, each functionality should have at least one example, and more often than not, just one example should be fine.
  11. The challenge is to provide a good example where
    1. the issue is taken from the real world and is something at which jQuery excels
    2. the problem can be cleanly stated and easily understood
    3. the solution is short and elegant
    4. the comment is short and remarks subtleties to watch out
    5. the Before and After are short, clean, and they work side by side in a diff fashion

Highlighting
The Solution, Before and After sections have to show context, but they exist mainly to show how to use the functionality. So I’ve introduced a means for drawing the reader’s attention to what is really important. All the text which in the documentation XML is wrapped by a grave accent (`) is highlighted using a css style.

jQuery: API documentation /2

Still about improving the official documentation.
|modified content, my style – snapshot for jQuery $( String, Object )
|official content, my style – snapshot for jQuery $( String, Object )
|official content & stylesnapshot for jQuery $( String, Object )

Functionality VS function
As an example of something that needs a rewrite take the $ function, which accepts many inputs and mostly does one of two things: either selects a group of elements into a DOM (possibly all of them), or creates a group of elements from scratch.

In the official documentation these two functionalities are mixed up in the filecard with one string argument, whereas the selection functionality with a string argument is split among two filecards, depending on wether there is only one argument for the string or also a second argument for the context. In case of one argument, the functionality does not change because a default value is used for the context.

The signature of a function
A very good thing in the official documentation is the use of type declarations for functions and arguments. Javascript is loosely typed and this is just a handy trick. I think I found a problem related to how much it is used.

The name of a function cannot be adapted in the documentation to reflect its type, so a declaration like Array<Element> get() makes a lot of sense. A different approach is needed for an argument name, which certainly can get a new name in the documentation. For the sake of readers, the same pseudo types should be used as much as possible for arguments as well. In fact, if an argument can get different types without changing the functionality of the function, then it’s much better to use a generic Object type and add a comment than it is to use a more specifiic Element type just because it is the most frequent use of that argument. In the former case the reader gets a hint at a nuance to whatch out, in the latter they need to carefully read the filecard to get the nuance.

The pseudo signature of a function can be augmented also with default values for optional arguments, like other languages do. This improves the readability a bit more, because less words are needed in the documentation, as it is a visual device.

An id for each functionality
Having each functionality documented in its own filecard, a unique identifier for referencing them is then needed. For example, see also the code in 2 could be a short comment of an example in a filecard, where the reader can be made aware of watchouts related to that code. The longer see also the code in ‘jQuery $( String, Object )’ is more informative but would be harder to add in the source of jQuery and to create an hyperlink in the documentation. To implement: longer form automatically built from id

The benefits of an id for each functionality go well beyond that. When speaking or writing about jQuery functions, the use of an id could simplify the reference, though something like calling 32 from 154 causes 9 to hang should definitely be avoided, and for posterity is to be preferred something like (this purely fictitious) calling toggle (32) from oneunload (154) causes serialize (9) to hang (using Rev:123)

For a working sample, I’ve added an id attribute to the method element of the documentation XML. It’s now a decimal number, starting from 1, which I’ve assigned to the most used function of jQuery: jQuery $( String, Object ). For making straighforward the referencing in the documentation XML and hence in the js sources, you simply have to wrap a grave accent (`) around the id of a function, like see also the code in `2`. This works inside the description of a function or example, and inside the comment of an example.

© 2017 Notes Log

Theme by Anders NorenUp ↑