Re: [nant-dev] userdoc changes

Sat, 25 Oct 2003 13:43:46 -0700

The real advantage to the 1st level inlining of nested elements is that you can see the attributes right there. It is esp. useful when using arrays/collections of elements, like <arg> or <option>, so that you can see the attributes that are required and available.
 
 
Can I get a show of hands from people who like the inlining of docs for nested elements in the Task/DataType docs? (http://nant.sourceforge.net/skot/help/tasks/foreach.html)
 
 
I've changed the required attributes to use bold names instead of the whole line being red. This is a change that can be made using the stylesheet if anyone want to work on it for any further changes.
 
I'm still looking into the issues of missing classes. They seem to exist, just not at the right place. (After writing an email about data types I think I know what is going on.)
 
 
 
----- Original Message -----
Sent: Monday, October 20, 2003 4:22 AM
Subject: Re: [nant-dev] userdoc changes

Very nice Scott! Yes - there are some flaws in formatting but globally I like it much! Finally docs will be usable ;-)
 
Some mine thoughts:
 
[snip from Ian]
>I'm thinking that just
>having links to the nested element doc will be better than having it
>inline. In the compiler tasks for example there are 3 instances of
>fileset - sources, resources and references. Having the fileset doc
>embedded 3 times is a little redundant.
I like first level included - it is nice. Maybe in some shortened form?
That 3 times FileSet seems to contain some bug - there is no header between them (csc,solution,...)
Maybe "fileset" (and filters in future) could be exception (used through all tasks) and do not generate subelements for it.
 
2/ In http://nant.sourceforge.net/skot/help/tasks/csc.html required attribs are not sorted to top.
 
3/ try use bold instead of red color. Maybe only attr name in bold. Sorted in top should be enough though.
 
4/ <solution>/<webmap> seems to lost reference to WebMap objects.
 
Great work!
Martin
----- Original Message -----
Sent: Saturday, October 18, 2003 11:04 PM
Subject: [nant-dev] userdoc changes

I have done a little work on the userdocs.
 
I have made the following changes:
 
1.) Reworked the Nested Elements section to include inline docs for level 1 (it doesn't inline all docs down the chain, but just the first one) and links to the full docs
2.) Reworked the Attributes section reordering the properties and formatting based if they are required and are declared for the task, or from an ancestor.
3.) Documented support types that are used as Nested Elements of Tasks and Types.
4.) Separated Tasks, Types (globally declarable from DataTypeBase), and Elements into sep directories
 
These are were serious changes to the process (how the information is generated at the code and xslt level) and we need a long look for style and to make sure all the content is still there. I have put up a nightly build from the latest source.
 
Please look at the new form of the docs here: http://nant.sourceforge.net/skot/help/ and compare them to the nightly build http://nant.sourceforge.net/nightly/help/
 
Here is a good example of the changes:
 
Please feel free to correct any typos or mistakes in source control, or post a patch if you don't have commit access. I will be working more on this, and on creating some metadata classes to ease the development of looking at our task, type and element information. We need classes to help us with xml validation/loading, schema generation and documentation. Right now these processes all use the same type of code, but with significant changes, that may lead to differences (and probably already do) in our xml loading and documentation (html and xsd).
 
Thanks,
Scott
 
PS. I wanted to get these change up earlier than later so we can discuss any additional changes before I finish coding :)
PSS. There are some bad links on types.html that I already know about.

Reply via email to