DOC: Transfer the wiki FAQ page to Markdown documentation #4308

jhlegarreta · 2023-11-09T02:22:17Z

Transfer the wiki FAQ page to Markdown documentation: https://itk.org/Wiki/ITK/FAQ

Add the corresponding entry in the Learn section of the documentation index.

Take advantage of the transition to:

Update URLs, including changing http to https, fixing broken URLs,
etc.
Link ITK and VTK classes to their Doxygen documentation pages.
Highlight parts (e.g. class names) using Markdown syntax.
Refactor the data format section to: include mesh and point set, and
transform file format sections, mention other file formats potentially
supported by remote modules. Add links to the file format reference
pages, and the Doxygen documentation of the ITK IO classes involved.
Make the BibTeX list style consistent, remove broken URLs pointing to
old versions of the SW Guide or all pointing to the latest PDF
available online, etc.
Make the BibTeX list style consistent, remove broken URLs pointing to
old versions of the SW Guide or all pointing to the latest PDF
available online, etc.
Remove outdated paragraph about libraries to build visualization
applications.
Change mentions to ImageViewer to itkwidgets.
Prefer pointing to the Python imageio package over ImageMagick.
Mention itk-wasm dicom to read a volume from a DICOM series.
Reword the language binding section: remove Java and mention that
further bindings are available through SimpleITK and itk-wasm.
Remove the What does \Error opening hint file NOTFOUND` mean?`
section.
Remove the language binding/wrapping section, as it is outdated: it
refers to the current SWIG wrapping before it was integrated into the
ITK repository.
Remove mentions to section number and pages in the ITK SW Guide, as
they have changed and may change in the future.
Remove the emacs coding style section.
Rewrite the Vim coding style section, as ITK's coding style is now
enforced and/or checked automatically, and as ITK switched from
txx to hxx suffices some time ago.
Remove the empty What is the `ITK_TEMPLATE_VISIBILITY_DEFAULT`
CMake option?` section.
Remove the outdated Platform-specific questionssection.
Fix typos and grammar, and reword passages for better understanding.
Change the title to Frequently asked questions.

PR Checklist

No API changes were made (or the changes have been approved)
No major design changes were made (or the changes have been approved)

Documentation/docs/learn/faq.md

jhlegarreta · 2023-11-09T02:31:23Z

Documentation/docs/learn/faq.md

+in case of desperation.
+
+1. Use the [`itk::ImageSeriesReader`](https://itk.org/Doxygen/html/classitk_1_1ImageSeriesReader.html) in combination with the
+   `DicomSeriesFileNames`. For a full example on how to do this,


DicomSeriesFileNames does not exist as a class name.

Documentation/docs/learn/faq.md

jhlegarreta · 2023-11-09T02:39:19Z

Documentation/docs/learn/faq.md

+   (with the motto: "MIND is not DICOM"). This application loads
+   DICOM files over the network and export them in MetaImage format.
+   This application is open source and it is available at:
+   http://www.jeffro.net/mind/ and http://caddlab.rad.unc.edu/software/MIND/.


Links are broken. Is this relevant? @aylward ?

jhlegarreta · 2023-11-09T02:41:07Z

Sorry for being active only now; could not devote time to it during the day.

A few general notes:

Used bare Markdown. Not sure if we are using another flavor.
Did not add anchors to the titles.
Could not find the 3rd edition (2013) ITK SWG book ISBN, so the note is empty.
Changed InsightApplications to ITKApps: both were mentioned. Not sure if they are the same.
Kept pointing examples to ITK SWG examples, rather than ITK Sphinx.
IMO, the BibTeX entries of previous versions should go into a historical section, and we should always point to the latest edition.
And all BibTeX files should be at a single place (there are some at the ISC website, some in ITK, there is a How to cite in the ITK README, etc. IIRC) to avoid inconsistencies.
Links to other wiki pages that need to be transitioned:
https://itk.org/Wiki/ITK_File_Formats
~~https://itk.org/Wiki/FDA_Guidelines_for_Software_Development~~ See PR DOC: Transfer the wiki FDA SW guidelines page to Markdown documentation #4312.
https://itk.org/Wiki/ITK/Wrapping
https://itk.org/Wiki/ITK/Using_ITK_from_.NET
https://itk.org/Wiki/ITK/Testing
~~https://itk.org/Wiki/ITK_Hounsfield_Units~~ See PR DOC: Transfer the wiki HU page to Markdown documentation #4311.
~~https://itk.org/Wiki/ITK/DICOM~~ See PR DOC: Transfer the wiki DICOM page to Markdown documentation #4318.
~~https://itk.org/Wiki/ITK/Third_Party_Applications~~ See PR DOC: Transfer the wiki 3rd party apps page to Markdown documentation #4313.
Broken links that need to be fixed for which I did not find a replacement:
http://www.itk.org/SimpleITKDoxygen/html/Filter_Coverage.html
http://www.itk.org/CourseWare/Training/GettingStarted-II.pdf: closest is https://itk.org/Wiki/ITK/Course_Ware
http://www.itk.org/CourseWare/Training/RegistrationMethodsOverview.pdf
There are different types of wiki page deprecations, e.g.
https://itk.org/Wiki/ITKContribute
https://itk.org/Wiki/ITK/Examples/Iterators/ImageRegionIterator (content removed)

which one should be used?

We would need to pass a Markdown linter to all these files
Did not change line length after automatic conversion (72 vs 79).

A few in-line notes.

thewtex

Great start!

Documentation/docs/learn/faq.md

thewtex · 2023-11-09T14:08:29Z

Documentation/docs/learn/faq.md

+
+### Is ITK tested?
+
+Please see this page: [ITK/Testing](https://itk.org/Wiki/ITK/Testing).


needs refresh

thewtex · 2023-11-09T14:09:05Z

Documentation/docs/learn/faq.md

+
+Please see the [third party applications](https://itk.org/Wiki/ITK/Third_Party_Applications) page for
+visualization applications that used ITK to perform image
+reading/writing.


We should have a third-party applications page.

PR #4313.

Missing
https://itk.org/Wiki/ITK/Related_Software
https://itk.org/Wiki/ITK/Developer_Software

from https://itk.org/Wiki/ITK/Other_Software

thewtex · 2023-11-09T14:12:32Z

Links to other wiki pages that need to be transitioned:

I added to this issue: #4063

Those could also be added there so we have one place to keep track of them.

thewtex · 2023-11-09T14:13:38Z

wiki page deprecations

We could also consider placing a banner on the landing page.

jhlegarreta · 2023-11-10T01:13:17Z

@thewtex Addressed the comments. Others may be willing to chime in to answer the pending questions.

About the links to the Wiki pages that have not been transitioned, I do not think it is feasible to wait until all is transitioned to merge the contributions, as this is a large endeavor.

thewtex · 2023-11-10T02:50:10Z

@thewtex Addressed the comments. Others may be willing to chime in to answer the pending questions.

@jhlegarreta awesome!

About the links to the Wiki pages that have not been transitioned, I do not think it is feasible to wait until all is transitioned to merge the contributions, as this is a large endeavor.

I agree. If there is outdated content or wiki content, we should omit it for now, though, in my opinion.

Documentation/docs/learn/faq.md

thewtex · 2023-11-11T18:58:15Z

Documentation/docs/learn/faq.md

+   application that allows you to load DICOM series and export them in
+   MetaImage and Analyze format (among others). She graciously has made
+   this application publicly available at:
+   https://darkwing.uoregon.edu/~jolinda/MRIConvert/.


Perhaps we should replace with dcm2niix?

dcm2niix is great to convert to NIfTI, but not sure it is able to export to MetaImage, and to Analyze. Not about other tools.

thewtex

⛑️

Documentation/docs/index.md

Documentation/docs/learn/faq.md

jhlegarreta · 2023-11-13T04:42:03Z

Still seems to be present in the latest build previews.

Not sure about the direction of the comment. Should the section be removed? Maybe reworked to tell people how to build applications with ITK + VTK?

This paragraph can be removed.

Removed in 66fdb26.

Transfer the wiki FAQ page to Markdown documentation: https://itk.org/Wiki/ITK/FAQ Add the corresponding entry in the `Learn` section of the documentation index, and set the `maxdepth` to 1 to avoid showing the FAQ page sections. Take advantage of the transition to: - Update URLs, including changing `http` to `https`, fixing broken URLs, etc. - Link ITK and VTK classes to their Doxygen documentation pages. - Highlight parts (e.g. class names) using Markdown syntax. - Refactor the data format section to: include mesh and point set, and transform file format sections, mention other file formats potentially supported by remote modules. Add links to the file format reference pages, and the Doxygen documentation of the ITK IO classes involved. - Make the BibTeX list style consistent, remove broken URLs pointing to old versions of the SW Guide or all pointing to the latest PDF available online, etc. - Remove outdated paragraph about libraries to build visualization applications. - Change mentions to `ImageViewer` to `itkwidgets`. - Prefer pointing to the Python `imageio` package over `ImageMagick`. - Mention `itk-wasm dicom` to read a volume from a DICOM series. - Reword the language binding section: remove Java and mention that further bindings are available through SimpleITK and itk-wasm. - Remove the `What does \`Error opening hint file NOTFOUND\` mean?` section. - Remove the language binding/wrapping section, as it is outdated: it refers to the current SWIG wrapping before it was integrated into the ITK repository. - Remove mentions to section number and pages in the ITK SW Guide, as they have changed and may change in the future. - Remove the emacs coding style section, and the outdated paragraph about the CMake indentantion and syntax Vim file. - Rewrite the Vim coding style section, as ITK's coding style is now enforced and/or checked automatically, and as ITK switched from `txx` to `hxx` suffices some time ago. - Remove the empty `What is the `\`ITK_TEMPLATE_VISIBILITY_DEFAULT\` CMake option?` section. - Remove the outdated `Platform-specific questions`section. - Fix typos and grammar, and reword passages for better understanding. - Change the title to `Frequently asked questions`.

thewtex · 2023-11-17T16:21:11Z

Still seems to be present in the latest build previews.

Not sure about the direction of the comment. Should the section be removed? Maybe reworked to tell people how to build applications with ITK + VTK?

Sorry for the lack of clarity. I think I was referencing an additional paragraph that was out-of-date that is gone.

In the future, we could link to the itk-vtk python interface #4320, but there is a lot of great content here. I think we should get it in and start building on it.

thewtex

Thank you @jhlegarreta !

Documentation/docs/learn/faq.md

github-actions bot added type:Documentation Documentation improvement or change area:Documentation Issues affecting the Documentation module labels Nov 9, 2023