[Insight-developers] developing formal documentation

[brian avants]

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- <mstauff at verizon.net> 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:anonymous at www.itk.org:/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