Torsten, i appreciate the thought you are putting in. I just wonder if the definition of the help (the raw content) should also be bound up with the definition of the overall structure? I also wonder if I want to bend the help system in a way that it is not intended.
For me i want something that is like python doc strings, and the great python package documentation available, ... but in a more smalltalk in-image manner. So that's why i think of it in terms of annotations. Having the help be in its own help class, on the class side, without any real behavior is a design smell to me. I don't really like heavy class-side programming; the class doesn't really offer any behaviour or scale across the image. I guess i want to see docs spread across the system. you want them central? to me the classes are really just annotations, apart from as you say needing to provide the role of structure for the nested content. my use case is that the documentation must be next to the code it is documenting. the network package is a good example. Since the API is in a state of flux, and no one knew how the 'new' api was supposed to work, it could really benefit detailed documentation for each version of pharo. it will change likely for each major version. the docs need to be in the package. fine, we can have the requisite 2 classes already in the image. that is ok. but it would be better to have the doc content on the actual system classes themselves. Like NetNameResolver. and Socket, etc. so i either have to have my custom class reference them, in some imperative manner, or i need to build a builder.. or something. I had imagined it would be possible to have standard places/hooks for packages and classes, where annotations would go. for example like stef says we could pull out the class comment. also, i imagine if documenting the system, in a system wide manner, was successful we would have lots of doit expressions. some mashup between workspaces, profstef, and hypertext. in that case it would be nice to somehow link doc expressions that are really little test assertions together, so we can actually test the docs to make sure that they validate against the system code. I think the SBE/PBE latex sources had this idea in them. And Adrian K has posted examples of these nice extensions to sunit that read very well. I would like that feeling somehow integrated, otherwise we won't be able to maintain the sanity of our docs either. so i guess i'm kinda with stef's comments later in this thread. but anyway, we start with zero in-image documentation. for me we must just have a doc system that scales. i really want to see the docs in the packages, not in a single central package. we'll just have to see how it plays out. i don't want to take away from building a 'help system' that would let you provide F1 style help for an actual application - we just desperately need system level documentation to take Pharo to the next level. I guess I see no need for defining inter-help structure because I think for system level docs it can be entirely derived. each package, class, method can all be annotated in a consistent manner. programming examples could be attached to classes in a standard manner. you could then provide a browser giving A-Z, hierarchy, package, classes, search, index, etc views on these annotations. This is not what you are trying to do with your help system, but i see this as a subset of the intent and a lot of the logic already there. i'm not sure if i'm making any sense... cheers, Mike _______________________________________________ Pharo-project mailing list [email protected] http://lists.gforge.inria.fr/cgi-bin/mailman/listinfo/pharo-project
