[vtk-developers] Request for Feedback: VTK Textbook Strawman

[Will Schroeder]

This is a really great work, thanks Bill! It would be great to get the book
out there so the community can fix, improve and extend it.

To ask a dumb question. and I don't have skin this game either, is markdown
the best way to go? Is a LaTeX book better? From what I understand here are
tools that convert framemaker to LaTeX etc. I suspect that with LaTeX you'd
end up with a better quality result, including things like indexing, cross
referencing, etc. And are there other options we should consider?

Best,
Will





On Thu, Mar 29, 2018 at 3:22 PM, Bill Lorensen <bill.lorensen at gmail.com>
wrote:

> 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://lorensen.github.io/VTKExamples/site/VTKBook/Chapter6/
>
> 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://lorensen.github.io/VTKExamples/site/VTKBookFigures/). 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://lorensen.github.io/VTKExamples/site/VTKBookFigures/).
> 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
>



-- 
William J. Schroeder, PhD
Kitware, Inc. - Building the World's Technical Computing Software
28 Corporate Drive
Clifton Park, NY 12065
will.schroeder at kitware.com
http://www.kitware.com
(518) 881-4902
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://vtk.org/pipermail/vtk-developers/attachments/20180330/4bb6985e/attachment.html>