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
