Hi Hans, Brian, Michael, I will not be able to make the October meeting, but I concur that generating the next stage of the Software Guide is very important, we should consolidate efforts, and we should avoid hard to maintain line-number references.
Thanks, Matt On Thu, Sep 13, 2012 at 9:10 PM, brian avants <[email protected]> wrote: > Everyone, > > Great. Let's discuss @ the oct meeting. I've used all the mentioned > approaches, including sphinx. > > I think we need to invent something that does not use line numbers. Its > doable. > > Anyway, discuss in october. > > B > > On Sep 13, 2012 8:53 PM, "Johnson, Hans J" <[email protected]> wrote: >> >> Brian and Matt and others, >> >> Could we talk about this during the October meeting? I've also negotiated >> some protected time from my department (in December/January) to work on >> updating the software guide. I've also got some outstanding JIRA tickets >> that are related to preparing for a new software guide, along with many >> fixes to the comments and code in ITK over the past year. >> >> I've got some outlines of material that is no longer relevant, and notes >> from my course teachings about deficiencies/outdated materials that >> mislead the user on how the toolkit should be used because it had evolved >> away from the original documentation. >> >> It is my feeling that this is a VERY important document for the community, >> and it has been neglected for far too long. My git hub repository has >> focused on the build/extration mechanism and it has a 95% rewrite of the >> extraction process written in python, and I've also worked on updating the >> graphics and style of LaTeX. >> >> Please let me know if you will be at the October meeting so that we can >> keep from duplicating efforts. >> >> Hans >> >> >> On 9/13/12 7:45 PM, "Matt McCormick" <[email protected]> wrote: >> >> >Hi Brian and Michael, >> > >> >Your documentation efforts for the registration v4 would be be greatly >> >appreciated by the community. >> > >> >Regarding where to place the documentation, there is not one clear >> >answer at this point. There have been various efforts to start a v4 >> >version of the Software Guide including this one by Arnaud: >> > >> > https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide >> > >> >This one by Hans: >> > >> > https://github.com/hjmjohnson/ITKSoftwareGuide >> > >> >And this one by myself, Arnaud, and David Doria intended to contain >> >examples separate from "guide" material: >> > >> > https://github.com/InsightSoftwareConsortium/ITKExamples >> > http://itk.org/ITKExamples/ >> > >> >Maybe there are others, too. As far as I know, none are "complete", >> >i.e. they do not have all the material from the v3 Software Guide. I >> >am semi-actively working on the last. I think picking any one of >> >these to start adding content would not be a bad choice, because it >> >can always be aggregated in the future. >> > >> >Re: code and line numbers: I think the one Hans was working is based >> >off the same previous perl parser (he may correct me). The first and >> >third are based on Sphinx: >> > >> > http://sphinx.pocoo.org/ >> > >> >A powerful, popular, elegant documentation system. For sphinx, either >> >the entire file can be included or a section of the file. However, >> >the sections are specified by line numbers. While I looked quite hard >> >for a way to not use line numbers, it appears to be the best option at >> >this point. At least two copies of the code are not maintained, and >> >everything that is presented is also tested. >> > >> >Thanks, >> >Matt >> > >> >On Thu, Sep 13, 2012 at 7:56 PM, brian avants <[email protected]> wrote: >> >> following up on this ... >> >> >> >> ideally, we would like to extract sections of code already in the ITK >> >> main repository with directives that allow it to be included in a >> >> latex document. >> >> >> >> for example >> >> >> >> // \begin{AddToLatexSectionX} >> >> ...some code >> >> // \end{AddToLatexSectionX} >> >> >> >> as opposed to just extracting line numbers from the source code. >> >> that's a problem because the line numbers can change over time which >> >> will create a dual maintenance and testing issue. >> >> >> >> is there an established way of doing this? if not, we can establish >> >> our own approach if it's acceptable to pollute some testing code with >> >> directives like those above. >> >> >> >> thanks, as usual, for your time, >> >> >> >> brian >> >> >> >> >> >> >> >> >> >> On Thu, Sep 13, 2012 at 6:32 PM, M Stauffer -V- <[email protected]> >> >>wrote: >> >>> Hi, >> >>> >> >>> Brian Avants and I are working on more formal end-user documentation >> >>>for >> >>> the new v4 registration framework. >> >>> >> >>> Our first thought is to develop something along the lines of the v3 >> >>>"ITK >> >>> Software Guide". Any reason we should take a different approach? >> >>> >> >>> We'd like to incorporate code from existing examples directly by >> >>> reference to the example source code files, as the software guide >> >>> does. >> >>> I downloaded the documentation project directly via >> >>> >> >>> cvs -d :pserver:[email protected]:/cvsroot/Insight checkout >> >>> InsightDocuments >> >>> >> >>> First off, is this the latest version of this? It's referenced in the >> >>> main itk.git repo's Documentation/README.html. >> >>> >> >>> Within this branch/directory, I see instructions and the scripts for >> >>> parsing latex-marked-up source code files in >> >>> InsightDocs/InsightDocuments/SoftwareGuide, for example >> >>> ParseCxxExamples.pl. These seem to be the documents I need to follow >> >>>the >> >>> same approach as the software guide - might there be other >> >>> instructions >> >>> or helpful files elsewhere? >> >>> >> >>> -M >> >>> >> >>> _______________________________________________ >> >>> Powered by www.kitware.com >> >>> >> >>> Visit other Kitware open-source projects at >> >>> http://www.kitware.com/opensource/opensource.html >> >>> >> >>> Kitware offers ITK Training Courses, for more information visit: >> >>> http://kitware.com/products/protraining.php >> >>> >> >>> Please keep messages on-topic and check the ITK FAQ at: >> >>> http://www.itk.org/Wiki/ITK_FAQ >> >>> >> >>> Follow this link to subscribe/unsubscribe: >> >>> http://www.itk.org/mailman/listinfo/insight-developers >> >> _______________________________________________ >> >> Powered by www.kitware.com >> >> >> >> Visit other Kitware open-source projects at >> >> http://www.kitware.com/opensource/opensource.html >> >> >> >> Kitware offers ITK Training Courses, for more information visit: >> >> http://kitware.com/products/protraining.php >> >> >> >> Please keep messages on-topic and check the ITK FAQ at: >> >> http://www.itk.org/Wiki/ITK_FAQ >> >> >> >> Follow this link to subscribe/unsubscribe: >> >> http://www.itk.org/mailman/listinfo/insight-developers >> >_______________________________________________ >> >Powered by www.kitware.com >> > >> >Visit other Kitware open-source projects at >> >http://www.kitware.com/opensource/opensource.html >> > >> >Kitware offers ITK Training Courses, for more information visit: >> >http://kitware.com/products/protraining.php >> > >> >Please keep messages on-topic and check the ITK FAQ at: >> >http://www.itk.org/Wiki/ITK_FAQ >> > >> >Follow this link to subscribe/unsubscribe: >> >http://www.itk.org/mailman/listinfo/insight-developers >> >> >> >> ________________________________ >> Notice: This UI Health Care e-mail (including attachments) is covered by >> the Electronic Communications Privacy Act, 18 U.S.C. 2510-2521, is >> confidential and may be legally privileged. If you are not the intended >> recipient, you are hereby notified that any retention, dissemination, >> distribution, or copying of this communication is strictly prohibited. >> Please reply to the sender that you have received the message in error, then >> delete it. Thank you. >> ________________________________ _______________________________________________ Powered by www.kitware.com Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html Kitware offers ITK Training Courses, for more information visit: http://kitware.com/products/protraining.php Please keep messages on-topic and check the ITK FAQ at: http://www.itk.org/Wiki/ITK_FAQ Follow this link to subscribe/unsubscribe: http://www.itk.org/mailman/listinfo/insight-developers
