[vtkusers] Request for Feedback: VTK Textbook Strawman

[Andras Lasso]

Thank you Bill, this is looks awesome! It is nicely readable - even on portrait screen orientation (e-readers, phones), searchable, hyperlinkable section titles.

One nice improvement would be to make figure reference (e.g., Figure6-39) hyperlinked to the figure, so that if I click on it then the page scrolls there.

Would be nice to make biblio references (e.g., [Wyszecki82]) hyperlinked, too, but only if it's easy to do.

Andras

-----Original Message-----
From: Bill Lorensen <bill.lorensen at gmail.com> 
Sent: Thursday, March 29, 2018 3:23 PM
To: VTK Developers <vtk-developers at vtk.org>; VTK Users <vtkusers at vtk.org>
Cc: Will <will.schroeder at kitware.com>; Ken <ken.martin at kitware.com>; Berk Geveci <berk.geveci at kitware.com>; Andras Lasso <lasso at queensu.ca>; Andrew Maclean <andrew.amaclean at gmail.com>
Subject: Request for Feedback: VTK Textbook Strawman

Folks,

Following my "bull in the china shop" approach to design by committee, I have converted Chapter 6 of the VTK Textbook to markdown and the mkdocs flavor.

See: https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Florensen.github.io%2FVTKExamples%2Fsite%2FVTKBook%2FChapter6%2F&data=02%7C01%7Classo%40queensu.ca%7Cd69312dd725d4229c7a608d595aa6c11%7Cd61ecb3b38b142d582c4efb2838b925c%7C1%7C0%7C636579481544635694&sdata=PctmleYfeo8Xkda2fsRZJlcybPoe7DgT5E2LtG%2FNnIY%3D&reserved=0

This approach is meant to be a Strawman.

Here is what I did:

1) I used pandoc to convert the VTK Textbook PDF to .txt and .md files. The conversion of the main text was excellent. Figures, tables, and equations not so good.

2) I cleaned up much of the cruft manually with emacs.

3) I added links to all of the VTKBookFigures (https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Florensen.github.io%2FVTKExamples%2Fsite%2FVTKBookFigures%2F&data=02%7C01%7Classo%40queensu.ca%7Cd69312dd725d4229c7a608d595aa6c11%7Cd61ecb3b38b142d582c4efb2838b925c%7C1%7C0%7C636579481544635694&sdata=y2MzDqU%2FIuambSesKZRlGMneBsTtc3JiOVQo5jN1Un0%3D&reserved=0). Andrew and I had created these a while ago. The figures contain links to the
C++ and Python code that generated the figures.

4) The chapter passes through the normal ScrapeRepo and SyncSiteWithRepo scripts that are used to maintain the static website.
As part of this process, I insert doxygen links to any vtk class mentioned in the document. I still have a small issue with this process.

Once I figured out an approach to handle figures, it took about 8 hours of manual labor to convert the chapter.

What needs to be done on the Chapter 6 Strawman?

1) Add the math.

2) Add the non-vtk generated figures.

3) More cleanup.

Other than 1 and 2, I will continue on cleanup.

There are several future issues.

Converting the text to markdown does not require a brain surgeon. But, editing the content to modern VTK will require more effort. Also, there are lots of old concepts. Andrew and I have already converted< all of the .tcl scripts to C++ and Python. They exist as examples on this page (https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Florensen.github.io%2FVTKExamples%2Fsite%2FVTKBookFigures%2F&data=02%7C01%7Classo%40queensu.ca%7Cd69312dd725d4229c7a608d595aa6c11%7Cd61ecb3b38b142d582c4efb2838b925c%7C1%7C0%7C636579481544635694&sdata=y2MzDqU%2FIuambSesKZRlGMneBsTtc3JiOVQo5jN1Un0%3D&reserved=0).
But subjects like the web should probably be replaced with the javascript stuff that is going on at Kitware.

Also, there are concepts that are not addressed in the current VTK Textbook including shaders, color management, etc.

Please provide feedback/suggestions. I don't have much skin in this game. If the approach looks wrong I'll gladly remove the current strawman and reconcentrate my efforts on making the VTKExamples better.


Bill