ajpmaclean
commented
6 years ago At this stage there will be many inconsistencies.
Don't worry too much about this, I'll get the LaTeX version consistent in a subsequent pass when all the chapters are in.
However: 1) I'll fix the subsubsec: issues, it is being fixed in other chapters. 2) If there is no reference to a section/subsection, there is no need for a label. 3) I'll fix chapter labels. 4) Duplicated labels are already fixed in other chapters, using a dot notation -- I'll fix these when I encounter them in a subsequent pass. 5) No rule for text style when referring to code yet. I'll fix this later. 6) Links to Doxygen may be automated in a future pass. However we need to be selective here, and it may not even happen. 7) Chapter/section labels will be rationalised.
The important thing is to get Chapter 4 into the document. Once this is done we can make the document more consistent.
I'll do chapter 11 over the next few days.
Andrew
Andrew Maclean
On Sun, 13 May 2018, 19:55 Jon Haitz Legarreta Gorroño < notifications@github.com> wrote:
I've noticed a number of inconsistencies throughout the Markdown/LaTeX files. In order to have a set of guidelines, I think having some answers to the following issues would be nice:
-
General comments
Should we use bold font when referring to examples?
- How should we refer to subfigures?
Figure \ref{fig:Figure3-25} (b)
or let both markdown (?) and LaTeX do the job?
Figure \ref{fig:Figure3-25b}
How should we refer to The VTK User's Guide VTK User's Guide or The VTK User's Guide?
- How should we write URL's in hyperlinks: www.whaterver.ext or protocol://www.whaterver.ext?
- Should we use the ampesand symbol (&) in headings or should we avoid it and use and?
LaTeX version
subsubsection are labeled as label{subsec:particular_label}. They should be label{subsubsec:particular_label}` to be consistent.
- Not all subsubsections have a label. Adding a label to them would allow cross-referencing them.
- Some chapter labels use lower cases with underscores, whereas others use cammel case with no underscores. Using a single criterion would help making all consistent.
- Do we have a rule to distinguish the labels for the sections that can be potentially duplicated (Chapter Summary, Bibliographic Notes, References, Exercises), e.g. Add the Chap0X prefix.
- Do we have a rule to use a different text style (whether it is `\texttt{}) when referring to actual code?
- Do we have a rule to use a different text style (i.e. a strategy to link with the Doxygen documentation) when referring to actual VTK classes?
- How do we want to write the chapter, section, etc. labels: just the same as their names, or dropping linking words such as and, articles such as the, an, etc.?
Markdowon version
Should we use the asterisk symbol (*) or undescores (_) to produce italics?
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/lorensen/VTKExamples/issues/174, or mute the thread https://github.com/notifications/unsubscribe-auth/AIJ4O-CFctnlLCxweoijORaMwXdbUTpbks5tyAMBgaJpZM4T8vFD .
jhlegarreta
I've noticed a number of inconsistencies throughout the Markdown/LaTeX files. In order to have a set of guidelines, I think having some answers to the following issues would be nice:
General comments
or let both markdown (?) and LaTeX do the job?
VTK User's GuideorThe VTK User's Guide?www.whaterver.extorprotocol://www.whaterver.ext?&) in headings or should we avoid it and useand?LaTeX version
subsubsectionare labeled aslabel{subsec:particular_label}. They should be label{subsubsec:particular_label}` to be consistent.subsubsections have a label. Adding a label to them would allow cross-referencing them.chapterlabels use lower cases with underscores, whereas others use cammel case with no underscores. Using a single criterion would help making all consistent.sections that can be potentially duplicated (Chapter Summary,Bibliographic Notes,References,Exercises), e.g. Add the Chap0X prefix.chapter,section, etc. labels: just the same as their names, or dropping linking words such asand, articles such asthe,an, etc.?Markdowon version
*) or undescores (_) to produce italics?