Just to emphasize the point, while the wiki (and the tutorials within it) are good for getting started, its proving (for me, at least) to be very poor as a reference. The wiki search functionality is not so hot. If such a manual doesn't exist, are there plans for one? Thanks -

Eliezer Kanal

On Aug 13, 2008, at 12:33 PM, Pedro Paulo de Magalhães Oliveira Junior wrote:

I think the manual is spread among the wiki pages.

However I think to start up the best way is using the tutorials: http://surfer.nmr.mgh.harvard.edu/fswiki/Tutorials

Pedro Paulo Jr

2008/8/13 Eliezer Kanal ejk4@pitt.edu 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

--

Pedro Paulo de M. Oliveira Junior Diretor de Operações Netfilter & SpeedComm Telecom

If you are just getting started, this is the best place.

http://surfer.nmr.mgh.harvard.edu/fswiki/RecommendedReconstruction

Once you have the basics the wiki is much more manageable. I think manual is at the bottom of the list because functionality is at the top.

Anthony

Eliezer Kanal wrote:

Just to emphasize the point, while the wiki (and the tutorials within it) are good for getting started, its proving (for me, at least) to be very poor as a reference. The wiki search functionality is not so hot. If such a manual doesn't exist, are there plans for one? Thanks -

Eliezer Kanal

On Aug 13, 2008, at 12:33 PM, Pedro Paulo de Magalhães Oliveira Junior wrote:

...

I think the manual is spread among the wiki pages.

However I think to start up the best way is using the tutorials: http://surfer.nmr.mgh.harvard.edu/fswiki/Tutorials

Pedro Paulo Jr

2008/8/13 Eliezer Kanal ejk4@pitt.edu 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

--

Pedro Paulo de M. Oliveira Junior Diretor de Operações Netfilter & SpeedComm Telecom

---

Freesurfer mailing list Freesurfer@nmr.mgh.harvard.edu https://mail.nmr.mgh.harvard.edu/mailman/listinfo/freesurfer

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

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:

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

I agree. We have out hands full writing unit/system tests, developing new algorithms and tracking down bugs. We try to keep the docs up to date, but it's pretty hard to do. If people were willing to contribute short pieces of documentation for different tools that they are familiar with, we can try to put it together into something coherent. Nick: maybe this should be done in Doxygen format so we can paste it right into the code, which will of course help the open source effort?

thanks Bruce On Thu, 14 Aug 2008, Eliezer Kanal wrote:

That's a great idea. I know that would have been helpful for me when doing my first run-through.

Eliezer

On Aug 14, 2008, at 7:00 AM, Pádraig Kitterick wrote:

...

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

---

Freesurfer mailing list Freesurfer@nmr.mgh.harvard.edu https://mail.nmr.mgh.harvard.edu/mailman/listinfo/freesurfer