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