I think at least part (1) of Eliezer's list is possible with the existing content on the FS wiki. Specifically, now that the wiki is using MoinMoin v1.6 it is possible to export pages as latex (see http://moinmo.in/FormatterMarket for the formatter plugin) which would be a very fast way to put together an offline manual. Even if it only contained the install docs, recommended reconstruction, recon-all dev table, and perhaps some of the tutorial pages it would be very very useful and relatively easy to keep in sync with the wiki. Having that information in printed form beside you can really help. I'd be willing to help compile various pages into a nicely-formatted latex doc if you need.
Obviously, a reference manual would be fantastic in the longer term, but having written tonnes of code with too little documentation, even when I intended to document as I developed, I can understand the massive challenge that is comprehensive documentation. Is there something to be said of tackling the command list (http://surfer.nmr.mgh.harvard.edu/fswiki/FreeSurferCommands) one at a time through the mailing list to try to compile information about the options/syntax for each command? I'm thinking specifically about the 'Description' and 'Examples' sections. There is probably a lot of shared knowledge out there which has yet to be committed to the wiki...
-Padraig
Nick Schmansky wrote:
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:
- installation instructions
- a walkthrough for the test dataset
- 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