<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content="text/html; charset=utf-8" http-equiv=Content-Type>
<META name=GENERATOR content="MSHTML 8.00.6001.19258"></HEAD>
<BODY>
<DIV dir=ltr align=left><SPAN class=765144301-14092012><FONT size=2
face=Verdana>Brian, the previous software guide used custom scripts
available in the documentation repo. These process markups within the
source code for the sections to be extracted and included in documentation. So
we probably needn't invent anything new in that regard, seeing as these scripts
could be repurposed even if the new documentation is done in
sphinx.</FONT></SPAN></DIV>
<DIV dir=ltr align=left><SPAN class=765144301-14092012><FONT size=2
face=Verdana></FONT></SPAN> </DIV>
<DIV dir=ltr align=left><SPAN class=765144301-14092012><FONT size=2
face=Verdana>-M</FONT></SPAN></DIV><BR>
<BLOCKQUOTE
style="BORDER-LEFT: #000000 2px solid; PADDING-LEFT: 5px; MARGIN-LEFT: 5px; MARGIN-RIGHT: 0px"
dir=ltr>
<DIV dir=ltr lang=en-us class=OutlookMessageHeader align=left>
<HR tabIndex=-1>
<FONT size=2 face=Tahoma><B>From:</B> insight-developers-bounces@itk.org
[mailto:insight-developers-bounces@itk.org] <B>On Behalf Of </B>brian
avants<BR><B>Sent:</B> Thursday, September 13, 2012 9:11 PM<BR><B>To:</B>
Johnson, Hans J<BR><B>Cc:</B> Terry Yoo;
ITK-dev-list-mstauff@ver<BR><B>Subject:</B> Re: [Insight-developers]
developing formal documentation<BR></FONT><BR></DIV>
<DIV></DIV>
<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
style="BORDER-LEFT: #ccc 1px solid; MARGIN: 0px 0px 0px 0.8ex; PADDING-LEFT: 1ex"
class=gmail_quote>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></BLOCKQUOTE></BODY></HTML>