Skip to content

Commit d29d655

Browse files
author
Jon Haitz Legarreta
committed
DOC: Add a section for SW Guide example writing.
Add a section for writing examples used in the ITK Software Guide. Although some overlap exists with the [LaTeX README.md file](https://github.com/InsightSoftwareConsortium/ITKSoftwareGuide/blob/master/SoftwareGuide/Latex/README.md), this was motivated by the constant build failures reported by CI builds, and addressed for this time in: http://review.source.kitware.com/#/c/23473/1 Also, emphasize the column limit in the mentioned `README` file.
1 parent d8d975a commit d29d655

File tree

2 files changed

+57
-1
lines changed

2 files changed

+57
-1
lines changed

SoftwareGuide/Latex/Appendices/CodingStyleGuide.tex

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3747,6 +3747,62 @@ \subsection{Test Return Value}
37473747
allowed in ITK.
37483748
37493749
3750+
\section{Writing Examples}
3751+
\label{sec:WritingExamples}
3752+
3753+
Many ITK examples are used in this software guide to demonstrate ITK's
3754+
architecture and development.
3755+
3756+
Thanks to scripting work, parts of the \code{*.cxx} example files within
3757+
special placeholders are included in this software guide. The \LaTeX
3758+
placeholders available to the code for such purpose are:
3759+
3760+
\begin{itemize}
3761+
\item \textbf{Software Guide : BeginLatex} and
3762+
\textbf{Software Guide : EndLatex}: the text within these placeholders is
3763+
included in this software guide for text explanations, e.g.
3764+
3765+
\small
3766+
\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{cpp}
3767+
// Software Guide : BeginLatex
3768+
//
3769+
// Noise present in the image can reduce the capacity of this filter to grow
3770+
// large regions. When faced with noisy images, it is usually convenient to
3771+
// pre-process the image by using an edge-preserving smoothing filter. Any of
3772+
// the filters discussed in Section~\ref{sec:EdgePreservingSmoothingFilters}
3773+
// could be used to this end. In this particular example we use the
3774+
// \doxygen{CurvatureFlowImageFilter}, so we need to include its header
3775+
// file.
3776+
//
3777+
// Software Guide : EndLatex
3778+
\end{minted}
3779+
\normalsize
3780+
3781+
\item \textbf{Software Guide : BeginCodeSnippet} and
3782+
\textbf{Software Guide : EndCodeSnippet}: the text within these placeholders is
3783+
included in this software guide for verbatim code snippets, e.g.
3784+
3785+
\small
3786+
\begin{minted}[baselinestretch=1,fontsize=\footnotesize,linenos=false,bgcolor=ltgray]{cpp}
3787+
// Software Guide : BeginCodeSnippet
3788+
#include "itkCurvatureFlowImageFilter.h"
3789+
// Software Guide : EndCodeSnippet
3790+
\end{minted}
3791+
\normalsize
3792+
3793+
\end{itemize}
3794+
3795+
Note that anything inside these gets inserted into the document; avoid blank
3796+
lines or too much whitespace. Make sure any \LaTeX comments included in the
3797+
code are correct in terms of grammar, spelling, and are complete sentences.
3798+
3799+
Note that \textbf{the code should not exceed 79 columns} or it will go out of
3800+
margins in the final document.
3801+
3802+
It is recommended that the \LaTeX comment blocks are aligned to the code for
3803+
the sake of readability.
3804+
3805+
37503806
\section{Doxygen Documentation System}
37513807
\label{sec:DoxygenDocumentationSystem}
37523808

SoftwareGuide/Latex/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Style Guidelines for the ITK Software Guide
4646
Anything inside these gets put into the document; avoid blank lines or too
4747
much whitespace. Make sure any comments in included code are correct in
4848
terms of grammar, spelling, and are complete sentences.
49-
Note that the code should not exceed column 80 or it will go out of
49+
Note that **the code should not exceed 79 columns** or it will go out of
5050
margins in the PDF document.
5151

5252
7. Figure/table captions should be proper sentences and end in a period

0 commit comments

Comments
 (0)