DOC: Adjust title of ImageBufferAndIndexRange example

[N-Dekker]

Following the guideline on how the write a title, at
https://examples.itk.org/documentation/contribute/writeanewexample#title
which suggests filling out the dots ("...") of the question, "How do I ...?"

[N-Dekker]

@thewtex @tbirdso Is it OK to you to extend the title to "Iterate Over an Image Buffer and an Index Range", while still keeping the name of the directory and the test project short (ImageBufferAndIndexRange)?

I'm asking specifically because on Windows, long directory path names still appear troublesome, nowadays! So I'm reluctant to rename the directory to something like "IterateOverAnImageBufferAndAnIndexRange". Unless you insist 😃

[dzenanz]

Are there other examples of larger discrepancy between directory name and example title?

[tbirdso]

@N-Dekker I agree with the motivation to keep the directory name short if possible. I am not sure if the docs style check will allow an example name that differs from the parent directory. Let's see whether build-test-documentation returns a warning.

[N-Dekker]

FYI, I just figured out (*) that the longest ITKSphinxExamples src directory path name so far is:

Filtering\ImageFilterBase\PredefinedOperationToCorrespondingPixelsInTwoImages

So Core\Common\IterateOverAnImageBufferAndAnIndexRange would still be shorter than the longest existing path anyway.

---

(*) PS I estimated the longest directory path name by the following code: https://godbolt.org/z/hdKneP97P

#include <filesystem>
#include <iostream>

int main()
{
  size_t longestPathLength{};

  for (const auto& entry : std::filesystem::recursive_directory_iterator("."))
  {
    const auto path = entry.path();
    const auto pathLength = path.string().size();

    if (std::filesystem::is_directory(path) && pathLength > longestPathLength)
    {
      longestPathLength = pathLength;
      std::cout << longestPathLength << " chars: " << path.string() << std::endl;
    }
  }
}

[N-Dekker]

When I tried to build ITKSphinxExamples for the first time (on Windows), I did encounter those CMake errors, even while my local source and build directory path names were rather short, in my opinion (something like "D:\X\source\ITKSphinxExamples" and "D:\X\build\ITKSphinxExamplesSuper"):

ITKSphinxExamples/CMakeLists.txt

Lines 64 to 75 in 66cbdd6

	if(${source_len} GREATER 30)
	message(FATAL_ERROR
	"The source directory is currently too long, ${source_len} characters. "
	"Please move the Examples source directory to a shorter path."
	)
	endif()
	string(LENGTH "${ITKSphinxExamples_BINARY_DIR}" binary_len)
	if(${binary_len} GREATER 30)
	message(FATAL_ERROR
	"The build directory is currently too long, ${binary_len} characters. "
	"Please set the Examples build directory to a shorter path."
	)

[thewtex]

Yes, we may need to diverge on the Windows and example name for path length issues.

[tbirdso]

@N-Dekker Checks passed, great! Yes, Windows paths are a pain point here, it may be worthwhile for us to revisit and rename example directories with long titles as you found. In CI we use C:/Ex for the source directory and C:/Ex/ITK-build for the build directory.