Eliezer, Thank you for the input. We'd like to automate the generation of documentation when we can get some work-cycles to do so. I agree the wiki can be a bit of a hunting expedition to get information (but isn't that half the fun :).
About a year ago, we started using Doxygen-style commenting in our code to document at the file level, and somewhat at the function level. This work occurs whenever a file is visited, so it will take some time before enough of the codebase is covered to allow the Doxygen HTML generation to be useful. This type documentation would only be useful to programmers though. A document listing each executable's usage (essentially a printing of the --help output) is needed for the general audience. Nick On Wed, 2008-08-13 at 17:40 -0400, Eliezer Kanal wrote: > Well, I'm no editor, but in my mind a comprehensive manual would > contain the following: > > 1) installation instructions > 2) a walkthrough for the test dataset > 3) descriptions for each program: > a) a summary of each program > b) acceptable program input > c) a description of the output of each program > > In my mind, the goal of the manual would be twofold: (1) someone who > never saw the program could use the install and "quick how-to" to get > a feel for it, and (2) a reference manual for people who use it all > the time but are now trying to use some program or feature they aren't > familiar with. > > So long as we're talking ideas here, I recently learned about Doxygen > <http://www.stack.nl/~dimitri/doxygen/ > >, a documentation system for a whole bunch of coding languages. The > idea is that you insert latex-style comments into your code and > Doxygen can automatically create the documentation when you're > finished. (See www.itk.org/ItkSoftwareGuide.pdf for an example of what > this can produce, as well as the examples on the website.) Obviously, > I'm not suggesting that you go add comments to the gazillions of lines > of code in the freesurfer codebase just for this, but it may be an > idea for the future. > > Eliezer Kanal > > > On Aug 13, 2008, at 5:15 PM, Bruce Fischl wrote: > > > Hi Eliezer, > > > > we had a manual some years ago, but found the wiki was much easier to > > keep current. What form would the manual take? A list of commands and > > usages? > > > > cheers, > > Bruce > > On Wed, 13 Aug 2008, Eliezer Kanal wrote: > > > >> Hello folks - > >> > >> I recently downloaded freesurfer and am slowly becoming more > >> familiar with > >> it. However, having to search through the myriad of pages on the > >> wiki every > >> time I have a question is very cumbersome, and more often than not, > >> fruitless. Is there a downloadable manual available anywhere? > >> Thanks - > >> > >> Eliezer Kanal > >> Graduate Student, Bioengineering > >> Center for Clinical Neurophysiology > >> University of Pittsburgh > >> > >> > >> > >> > >> > >> _______________________________________________ > >> Freesurfer mailing list > >> Freesurfer@nmr.mgh.harvard.edu > >> https://mail.nmr.mgh.harvard.edu/mailman/listinfo/freesurfer > >> > >> > >> > > _______________________________________________ > Freesurfer mailing list > Freesurfer@nmr.mgh.harvard.edu > https://mail.nmr.mgh.harvard.edu/mailman/listinfo/freesurfer > > _______________________________________________ Freesurfer mailing list Freesurfer@nmr.mgh.harvard.edu https://mail.nmr.mgh.harvard.edu/mailman/listinfo/freesurfer
