Re: Javasrc, JXR and documentation
Clay, Thanks for keeping this on the boil. The Forrestdoc link you gave me shows the Javasrc at a much greater level of integration than was visible when I last looked. My problem originally was that only line-number links were provided. In the current forrestdoc version, everything is linked in to comprehensive cross-reference web. Nice. The appearance of the the source text is not optimal, but there is scope in Javasrc to correct this, I believe. There are probably two levels of tuning. Firstly, syntax highlighting, and secondly. link presentation. The syntax highlighting variations (if any) would be Javasrc configuration options. The link presentation would be available through the CSS used to present the document. Most things of interest, and, AFAICT, all links are htmlized with a relevant class attribute, so it is feasible to select the link colour or colours for various classes to allow appropriate highlighting. Keywords, although emphasised in the text, are not given a class attribute, which is unfortunate, but may be tunable. The source html I used was generated by htmlize.el, an emacs and XEmacs module by Hrvoje Niksic. In order to use it, you will need to have an emacs or xemacs binary available to the build process. Forrestdoc looks the far better option. Peter Clay Leeds wrote: Peter, On Jun 29, 2004, at 7:04 PM, Peter B. West wrote: Clay, FYI, Java 1.4 javadoc tool supports a -linksource argument, which generates html of source files. However, the process seems to have pretty much the same restrictions as the Maven JXR - the only references are to line numbers, which is just about the most useless form imaginable. It might be of interest to someone at a later stage to look at extending the standard doclet to utilise Javasrc to perform that generation. Peter I've been hoping to get movement on the forrest front, then include the java doc stuff once I have xml-fop up running. As that's not moving along very fast, perhaps I can get a bit more information on what we need to do with the java doc front. Here's something I 'dug' up[1]. Looks like it's along the lines of what we're looking for, although I like what you've got on this page[2] better. Your version seems more accessible. However, you indicate: The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for. What is the procedure used to generate the htmlized source? Could it be automated using gump or ant or something? BTW, what's the tool called you use to generate this? Web Maestro Clay [1] http://cvs.apache.org/~nicolaken/whiteboard/forrestdoc/ [2] http://xml.apache.org/fop/design/alt.design/properties/classes- overview.html -- Peter B. West http://cv.pbw.id.au/
Re: Javasrc, JXR and documentation
Peter, On Jun 29, 2004, at 7:04 PM, Peter B. West wrote: Clay, FYI, Java 1.4 javadoc tool supports a -linksource argument, which generates html of source files. However, the process seems to have pretty much the same restrictions as the Maven JXR - the only references are to line numbers, which is just about the most useless form imaginable. It might be of interest to someone at a later stage to look at extending the standard doclet to utilise Javasrc to perform that generation. Peter I've been hoping to get movement on the forrest front, then include the java doc stuff once I have xml-fop up running. As that's not moving along very fast, perhaps I can get a bit more information on what we need to do with the java doc front. Here's something I 'dug' up[1]. Looks like it's along the lines of what we're looking for, although I like what you've got on this page[2] better. Your version seems more accessible. However, you indicate: The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for. What is the procedure used to generate the htmlized source? Could it be automated using gump or ant or something? BTW, what's the tool called you use to generate this? Web Maestro Clay [1] http://cvs.apache.org/~nicolaken/whiteboard/forrestdoc/ [2] http://xml.apache.org/fop/design/alt.design/properties/classes- overview.html
Re: Javasrc, JXR and documentation
On Jul 8, 2004, at 5:02 PM, Peter B. West wrote: Clay Leeds wrote: Peter, Did you get a chance to try the procedure Nicola recommended[1]? I haven't gotten a successful build yet, but I'm still working at it. When I do, I'll try to do as he suggested. No, I've been too busy working on the FAD layout lately. I can relate. Of course, there's also the 'issue' of you being a newlywed! Tell the Mrs. the 'guys' say 'Cheers!' :-) I actually was getting stuck on the BUILD portions, but I was still using forrest 0.5.1. Much of the forrest development is going towards 0.6 which I believe has an imminent release (days? weeks? months? :-D). With all of the stuff going on (XML Graphics, forrest.apache.org, etc.) coupled with the fact that the forrest-site 'skin' is a bit outdated, I thought it best to work toward a 0.6 version of the FOP website. At the same time I'll also change to one of the other skins (css-style, xhtml-css, krysalis-site, tigris-site, etc.). If anyone has a particular preference, please chime in! I'm leaning a bit toward the css-style, as it appears to offer the greatest flexibility, and seems to better leverage css over tables... But we'll see! As we're all anxious to see a Whole Site PDF (not to mention the 'new' logo :-D) I might use one of the others if css-style isn't ready in time. BTW, how does Simon's recent Documentation[2] figure in to this? I don't know. I think the fact that Simon's docs are Docbook based will militate against linking in to the sources, but Simon would be in the best position to answer this. If it could be done, it would be a great boon to the documentation. That actually shouldn't be too hard... It appears that forrest is pretty much built to work with docbook[3]. We can either just 'stick it in the directory' and It Should Just Work(tm)--albeit with limited transformation of the presumably more advanced DocBook elements, or we can use the full DocBook stylesheets themselves (which is probably the preferred method). Each has its own issues. [OT] militate? heh... there's a word I tend to 'try' to stay away from in every day conversation... (it's not that hard, as I don't think I've ever heard it...). [1] http://marc.theaimsgroup.com/?l=fop-devm=108680587917268w=2 [2] http://marc.theaimsgroup.com/?l=fop-devm=108844739724995w=2 [3] http://forrest.apache.org/faq.html#docbook Web Maestro Clay
Re: Javasrc, JXR and documentation
Clay Leeds wrote: Peter, Did you get a chance to try the procedure Nicola recommended[1]? I haven't gotten a successful build yet, but I'm still working at it. When I do, I'll try to do as he suggested. No, I've been too busy working on the FAD layout lately. BTW, how does Simon's recent Documentation[2] figure in to this? I don't know. I think the fact that Simon's docs are Docbook based will militate against linking in to the sources, but Simon would be in the best position to answer this. If it could be done, it would be a great boon to the documentation. [1] http://marc.theaimsgroup.com/?l=fop-devm=108680587917268w=2 [2] http://marc.theaimsgroup.com/?l=fop-devm=108844739724995w=2 Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html
Re: Javasrc, JXR and documentation
Peter, On Jun 29, 2004, at 7:04 PM, Peter B. West wrote: Clay, FYI, Java 1.4 javadoc tool supports a -linksource argument, which generates html of source files. However, the process seems to have pretty much the same restrictions as the Maven JXR - the only references are to line numbers, which is just about the most useless form imaginable. It might be of interest to someone at a later stage to look at extending the standard doclet to utilise Javasrc to perform that generation. Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html Did you get a chance to try the procedure Nicola recommended[1]? I haven't gotten a successful build yet, but I'm still working at it. When I do, I'll try to do as he suggested. BTW, how does Simon's recent Documentation[2] figure in to this? [1] http://marc.theaimsgroup.com/?l=fop-devm=108680587917268w=2 [2] http://marc.theaimsgroup.com/?l=fop-devm=108844739724995w=2
Re: Javasrc, JXR and documentation
Clay, FYI, Java 1.4 javadoc tool supports a -linksource argument, which generates html of source files. However, the process seems to have pretty much the same restrictions as the Maven JXR - the only references are to line numbers, which is just about the most useless form imaginable. It might be of interest to someone at a later stage to look at extending the standard doclet to utilise Javasrc to perform that generation. Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html
Re: Javasrc, JXR and documentation
On Jun 8, 2004, at 6:48 PM, Peter B. West wrote: It's not a question of moving away, necessarily. What I'm looking for is a supplementary facility. Look at http://xml.apache.org/fop/design/alt.design/properties/classes- overview.html and click on one of the class name links on the left of the main page, e.g. PropNames. That opens an iframe with the source. On linux, in Mozilla, it also positions the iframe at the top of the page. Clicking the link again - it's a toggle - restores the previous position of the page. When I first set is up, this tidy behaviour was not available on Windows using either Mozilla or IE, but that may have changed by now. FWIW, it works nicely in Mac OS X 10.3.4, Safari 1.2.2 (v125.7) (although it doesn't position the iFrame at the top of the page) as well as Mozilla 1.7b (where it *does* jump to the top of the iFrame). The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for. OK. I'll see what I can dig up on the subject. If you have any other keywords I can use in my search, by all means, send 'em my way! Web Maestro Clay
Re: Javasrc, JXR and documentation
Clay Leeds wrote: On Jun 8, 2004, at 6:48 PM, Peter B. West wrote: The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for. OK. I'll see what I can dig up on the subject. If you have any other keywords I can use in my search, by all means, send 'em my way! Clay, I would recommend emailing Nicola on the topic. I'm sure he would be only too pleased to tell you about the situation with Javasrc. Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html
Re: Javasrc, JXR and documentation
Peter, On Jun 9, 2004, at 8:06 AM, Peter B. West wrote: Clay Leeds wrote: On Jun 8, 2004, at 6:48 PM, Peter B. West wrote: The problem is that there was no clean way to automatically generate the htmlized source. It's that supplementary facility that I'm looking for. OK. I'll see what I can dig up on the subject. If you have any other keywords I can use in my search, by all means, send 'em my way! Clay, I would recommend emailing Nicola on the topic. I'm sure he would be only too pleased to tell you about the situation with Javasrc. Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html As you guessed, Nicola was only too happy to help. Now I just need to get the FOP site up and running with Forrest (so we can include Whole Site PDF HTML links on our site!). Web Maestro Clay Nicola's response is below: Begin forwarded message: From: Nicola Ken Barozzi [EMAIL PROTECTED] Date: June 9, 2004 10:13:13 AM PDT To: Clay Leeds [EMAIL PROTECTED] Subject: Re: Possibility of Using Javasrc for FOP Clay Leeds wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Hi Nicola, We are exploring the possibility of using Javasrc in generating cross-referenced source in html format, into which we can point from the web-site documentation. Here's the thread[1] to follow for info. Javasrc is now in Forrest scratchpad. Get Forrest from SVN, install graphviz [x1] for a complete build, cd into scratchpad/forrestdoc, then run build project -Dproject.dir=[enter base project dir here] It will generate documentation with javadocs, javasrc, ant docs with dependency graphs, full class diagram, javascript docs. Here is an example: http://cvs.apache.org/~nicolaken/whiteboard/forrestdoc/ Note that the colors of the java src can be made much more different, they are more varied than JXR. Peter West's alt-design has an example[2] of what we want to do: [Peter West] click on one of the class name links on the left of the main page, e.g. PropNames. That opens an iframe with the source. On linux, in Mozilla, it also positions the iframe at the top of the page. Clicking the link again - it's a toggle - restores the previous position of the page. [/Peter West] That's cool! Currently we are focusing on fixing bugs for a 0.6 release, but doing this is on my chart. Actually, what I would like to do is to integrate this forrestdoc in forrest, and have forrest create a complete pdf, htmlhelp and javahelp files for the whole site. Also in this I would like to add something like this, so that users can browse the javadocs and the source dynamically without having to statically generate all the docs (just an index): http://chaperon.sourceforge.net/screenshots.html And then integrate all these docs in our Lucene-based search. Please let me know if there's any other information I can provide. More precisely, what can I do for you? :-) Given the above, I think you have enough to start off helping somewhat. For any other discussion, please refer to [EMAIL PROTECTED] (soon [EMAIL PROTECTED]). TIA, and thanks for contacting me on this! Thanks! Web Maestro Clay [1] http://marc.theaimsgroup.com/?l=fop-devm=108670344811832w=2 [2] http://xml.apache.org/fop/design/alt.design/properties/classes- overview.html [x1] http://www.research.att.com/sw/tools/graphviz/ -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains)
Javasrc, JXR and documentation
Clay, Do you have time for some documentation investigations? Some time ago, a project called Javasrc was in the process of migrating from SourceForge to Apache. Nicola Ken Barozzi [EMAIL PROTECTED] was the one who initiated the discussions with the Javasrc developers. The code was originally to go into Alexandria, a project on which development has now ceased. I recall some discussion about the use of Javasrc outside the context of Alexandria. There is an alternative, in the JXR plugin for Maven. Joerg may be of help here, as he seems to be a fan of Maven. My primary interest in this question is in generating cross-referenced source in html format, into which I can point from the web-site documentation. At the moment I have some html source that I generated using Xemacs, but that is extremely tedious. If you have time, could you ask a few questions about the best way of having such cross-referenced html sources generated as part of the process of web site creation? Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html
Re: Javasrc, JXR and documentation
I'm unsure if this is related to your question, but I think it would be nice for us to switch to Docbook. Apparently at least one Apache project, Tapestry, is already using it with Forrest [1][2]. We switched at work from RoboHelp HTML to Docbook and it has been great for us. Glen [1] http://wiki.docbook.org/topic/WhoUsesDocBook [2] http://jakarta.apache.org/tapestry/doc.html --- Peter B. West [EMAIL PROTECTED] wrote: Clay, Do you have time for some documentation investigations? Some time ago, a project called Javasrc was in the process of migrating from SourceForge to Apache. Nicola Ken Barozzi [EMAIL PROTECTED] was the one who initiated the discussions with the Javasrc developers. The code was originally to go into Alexandria, a project on which development has now ceased. I recall some discussion about the use of Javasrc outside the context of Alexandria. There is an alternative, in the JXR plugin for Maven. Joerg may be of help here, as he seems to be a fan of Maven. My primary interest in this question is in generating cross-referenced source in html format, into which I can point from the web-site documentation. At the moment I have some html source that I generated using Xemacs, but that is extremely tedious. If you have time, could you ask a few questions about the best way of having such cross-referenced html sources generated as part of the process of web site creation? Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html
Re: Javasrc, JXR and documentation
Peter, On Jun 8, 2004, at 7:15 AM, Peter B. West wrote: Clay, Do you have time for some documentation investigations? Some time ago, a project called Javasrc was in the process of migrating from SourceForge to Apache. Nicola Ken Barozzi [EMAIL PROTECTED] was the one who initiated the discussions with the Javasrc developers. The code was originally to go into Alexandria, a project on which development has now ceased. I recall some discussion about the use of Javasrc outside the context of Alexandria. There is an alternative, in the JXR plugin for Maven. Joerg may be of help here, as he seems to be a fan of Maven. My primary interest in this question is in generating cross-referenced source in html format, into which I can point from the web-site documentation. At the moment I have some html source that I generated using Xemacs, but that is extremely tedious. If you have time, could you ask a few questions about the best way of having such cross-referenced html sources generated as part of the process of web site creation? Peter -- Peter B. West http://www.powerup.com.au/~pbwest/resume.html I'd be happy to do some research on this subject. I'll look into this and see what i can dig up. Before I spend time on this, it might make more sense to look into Docbook, as Glen mentioned. In addition, it would be good to spend some time checking out what other Apache projects are using for ideas. I would suspect that the most-used documentation system(s) would bear the most fruit for us. If for no other reason, than the sheer numbers of people banging on them. I assume we already have a system (I think it's Javadocs). I think it would also be good to determine if any of our colleagues have made the switch from our system to another. Finally, assuming we've already got a system, what are the reasons we're moving away from our current system? Complexity? Dead-end product? Etc. Web Maestro Clay
