styleguide: Reflect recent conversion of code snippets to listing
PATCH 1/1 styleguide: Reflect recent conversion of code snippets to listing
From cf16d20dff9bf4cf2832c1fdd1fe00b39c4836fd Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <[email protected]>
Date: Fri, 20 Oct 2017 07:16:48 +0900
Subject: [PATCH] styleguide: Reflect recent conversion of code snippets to listing
Also use a different approach to reduce skips of table captions. By setting a smaller value to \abovecaptionskip, captions of tables and figures can be made closer to the body regardless of their positions and avoid ambiguity of them to look like captions to other nearby tables/figures.
In the experimental tables, a negative value is still set to \abovetopsep to further reduce the skips.
As options of \captionsetup{} related to vertical spacing are ignored in captions controlled by the "float" package, remove them.
--- appendix/styleguide/styleguide.tex | 39 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 20 deletions(-)
appendix/styleguide/styleguide.tex +19 -20
@@ -374,7 +374,6 @@ the code snippet is coded as a ``figure'' object. Line numbers are manually placed for ease of referencing them within \LaTeX\ sources. -This is how most code snippets are coded as of this writing. However, strictly speaking, code snippets are \emph{not} figures and they deserve their own floating environment. The ``float'' package provides the feature to define additional
@@ -387,7 +386,11 @@ Transition to the auto-numbering scheme of verbbox and the ``listing'' environment defined for code snippets has recently started in Chapter~\ref{chp:Advanced Synchronization: Memory Ordering}. -The transition also permits us to choose distinct looks +In other chapters, code snippets have been converted to the +``listing'' environments without auto-numbering. +Auto-numbering can be enabled when the renumbering of line +numbers becomes necessary. +The transition has allowed us to choose distinct looks for code snippets, including moving captions to top of the listings (discussed in Section~\ref{sec:app:styleguide:Position of Caption}).
@@ -397,7 +400,7 @@ the \verb|\LstLineNo| macro specified in the option to verbbox (line~3 in Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}). The macro is defined in the preamble of \path{perfbook.tex} -as the following: +as follows: \noindent\begin{minipage}{\columnwidth} { \scriptsize
@@ -844,22 +847,16 @@ As for tables, the position of caption can be tweaked by \verb|\floatstyle{}| and \verb|\restylefloat{}| macros in preamble. -Currently, as most code snippets are figures with their captions -at the bottom, captions of tables at the top might look inconsistent. -Once the transition of code snippets to listing environment -completes, there would be fewer figures and the caption of tables -at the top would hopefully be acceptable. - -Vertical space between captions at the top and the table bodies -can be reduced by the help of ``ctable'' package. - In the sample tables shown in Sections~\ref{sec:app:styleguide:Ruled Line in Table} and~\ref{sec:app:styleguide:Table Layout Experiment}, -the vertical skip is manually reduced by setting a negative value to the -\verb|\abovetopsep| variable which controls the behavior of -\verb|\toprule| of the ``booktabs'' package. -It should be regarded as a band-aid tweak. +vertical skips below captions are reduced by setting a smaller +value to the \verb|\abovecaptionskip| variable, +which would also affect captions to figures.\footnote{ + The skip below table captions in these sections is further + reduced by setting a negative value to the \co{\\abovetopsep} + variable of the ``booktabs'' package which controls the behavior + of \co{\\toprule}.} \subsubsection{Grouping Related Figures/Listings} \label{sec:app:styleguide:Grouping Related Figures/Listings}
@@ -920,8 +917,9 @@ used sparingly, especially in tables of simple structure. \floatstyle{plaintop} \restylefloat{table} -\captionsetup[table]{position=top,hangindent=30pt} -\renewcommand*{\abovetopsep}{-7pt} +\captionsetup[table]{hangindent=30pt} +\setlength{\abovetopsep}{-2pt} +\addtolength{\abovecaptionskip}{-2.5pt} For example, Table~\ref{tab:future:Refrigeration Power Consumption}
@@ -1385,8 +1383,9 @@ for examples of tables with complex headings. \floatstyle{plain} \restylefloat{table} -\captionsetup[table]{position=bottom,hangindent=0pt} -\renewcommand*{\abovetopsep}{0pt} +\captionsetup[table]{hangindent=0pt} +\addtolength{\abovecaptionskip}{2.5pt} +\setlength{\abovetopsep}{0pt} \subsubsection{Miscellaneous Candidates} \label{sec:app:styleguide:Miscellaneous Candidates}
Signature · 1 line
2.7.4
Quoted 11 lines · Akira Yokosawa
Quoted 1 line
From
cf16d20dff9bf4cf2832c1fdd1fe00b39c4836fdMon Sep 17 00:00:00 2001From: Akira Yokosawa <[email protected]>
Date: Fri, 20 Oct 2017 07:16:48 +0900
Subject: [PATCH] styleguide: Reflect recent conversion of code snippets to listingAlso use a different approach to reduce skips of table captions. By setting a smaller value to \abovecaptionskip, captions of tables and figures can be made closer to the body regardless of their positions and avoid ambiguity of them to look like captions to other nearby tables/figures.
Quoted 7 lines
In the experimental tables, a negative value is still set to \abovetopsep to further reduce the skips.
As options of \captionsetup{} related to vertical spacing are ignored in captions controlled by the "float" package, remove them.
Signed-off-by Akira Yokosawa <[email protected]>
Applied and pushed, thank you!
Thanx, Paul
Quoted 95 lines
--- appendix/styleguide/styleguide.tex | 39 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 20 deletions(-)appendix/styleguide/styleguide.tex +19
-20@@ -374,7 +374,6 @@ the code snippet is coded as a ``figure'' object. Line numbers are manually placed for ease of referencing them within \LaTeX\ sources. -This is how most code snippets are coded as of this writing. However, strictly speaking, code snippets are \emph{not} figures and they deserve their own floating environment. The ``float'' package provides the feature to define additional@@ -387,7 +386,11 @@ Transition to the auto-numbering scheme of verbbox and the ``listing'' environment defined for code snippets has recently started in Chapter~\ref{chp:Advanced Synchronization: Memory Ordering}. -The transition also permits us to choose distinct looks +In other chapters, code snippets have been converted to the +``listing'' environments without auto-numbering. +Auto-numbering can be enabled when the renumbering of line +numbers becomes necessary. +The transition has allowed us to choose distinct looks for code snippets, including moving captions to top of the listings (discussed in Section~\ref{sec:app:styleguide:Position of Caption}).@@ -397,7 +400,7 @@ the \verb|\LstLineNo| macro specified in the option to verbbox (line~3 in Listing~\ref{lst:app:styleguide:LaTeX Source of Sample Code Snippet (Current)}). The macro is defined in the preamble of \path{perfbook.tex} -as the following: +as follows: \noindent\begin{minipage}{\columnwidth} { \scriptsize@@ -844,22 +847,16 @@ As for tables, the position of caption can be tweaked by \verb|\floatstyle{}| and \verb|\restylefloat{}| macros in preamble. -Currently, as most code snippets are figures with their captions -at the bottom, captions of tables at the top might look inconsistent. -Once the transition of code snippets to listing environment -completes, there would be fewer figures and the caption of tables -at the top would hopefully be acceptable. - -Vertical space between captions at the top and the table bodies -can be reduced by the help of ``ctable'' package. - In the sample tables shown in Sections~\ref{sec:app:styleguide:Ruled Line in Table} and~\ref{sec:app:styleguide:Table Layout Experiment}, -the vertical skip is manually reduced by setting a negative value to the -\verb|\abovetopsep| variable which controls the behavior of -\verb|\toprule| of the ``booktabs'' package. -It should be regarded as a band-aid tweak. +vertical skips below captions are reduced by setting a smaller +value to the \verb|\abovecaptionskip| variable, +which would also affect captions to figures.\footnote{ + The skip below table captions in these sections is further + reduced by setting a negative value to the \co{\\abovetopsep} + variable of the ``booktabs'' package which controls the behavior + of \co{\\toprule}.} \subsubsection{Grouping Related Figures/Listings} \label{sec:app:styleguide:Grouping Related Figures/Listings}@@ -920,8 +917,9 @@ used sparingly, especially in tables of simple structure. \floatstyle{plaintop} \restylefloat{table} -\captionsetup[table]{position=top,hangindent=30pt} -\renewcommand*{\abovetopsep}{-7pt} +\captionsetup[table]{hangindent=30pt} +\setlength{\abovetopsep}{-2pt} +\addtolength{\abovecaptionskip}{-2.5pt} For example, Table~\ref{tab:future:Refrigeration Power Consumption}@@ -1385,8 +1383,9 @@ for examples of tables with complex headings. \floatstyle{plain} \restylefloat{table} -\captionsetup[table]{position=bottom,hangindent=0pt} -\renewcommand*{\abovetopsep}{0pt} +\captionsetup[table]{hangindent=0pt} +\addtolength{\abovecaptionskip}{2.5pt} +\setlength{\abovetopsep}{0pt} \subsubsection{Miscellaneous Candidates} \label{sec:app:styleguide:Miscellaneous Candidates}Signature · 1 line
2.7.4
Quoted 15 lines · Paul E. McKenney
Quoted 14 lines · Akira Yokosawa
Quoted 1 line
From
cf16d20dff9bf4cf2832c1fdd1fe00b39c4836fdMon Sep 17 00:00:00 2001From: Akira Yokosawa <[email protected]>
Date: Fri, 20 Oct 2017 07:16:48 +0900
Subject: [PATCH] styleguide: Reflect recent conversion of code snippets to listingAlso use a different approach to reduce skips of table captions. By setting a smaller value to \abovecaptionskip, captions of tables and figures can be made closer to the body regardless of their positions and avoid ambiguity of them to look like captions to other nearby tables/figures.
In the experimental tables, a negative value is still set to \abovetopsep to further reduce the skips.
Quoted 6 lines
Quoted 4 lines
As options of \captionsetup{} related to vertical spacing are ignored in captions controlled by the "float" package, remove them.
Signed-off-by Akira Yokosawa <[email protected]>Applied and pushed, thank you!
So, looks like you are almost ready for the upcoming release. I'm preparing a patch to add a make target to move table captions to the top throughout perfbook.
Would you like to see such a patch before the upcoming release?
And I have a reminder for you.
You might want to update the "Roadmap" section in Chapter 1 to mention new Chapter 15. Style Guide can be ignored for the moment.
Thoughts?
Thanks, Akira
Quoted 3 lines
Thanx, Paul
[...]
Quoted 19 lines · Akira Yokosawa
Quoted 18 lines · Paul E. McKenney
Quoted 17 lines · Akira Yokosawa
Quoted 1 line
From
cf16d20dff9bf4cf2832c1fdd1fe00b39c4836fdMon Sep 17 00:00:00 2001From: Akira Yokosawa <[email protected]>
Date: Fri, 20 Oct 2017 07:16:48 +0900
Subject: [PATCH] styleguide: Reflect recent conversion of code snippets to listingAlso use a different approach to reduce skips of table captions. By setting a smaller value to \abovecaptionskip, captions of tables and figures can be made closer to the body regardless of their positions and avoid ambiguity of them to look like captions to other nearby tables/figures.
In the experimental tables, a negative value is still set to \abovetopsep to further reduce the skips.
As options of \captionsetup{} related to vertical spacing are ignored in captions controlled by the "float" package, remove them.
Quoted 8 lines
Quoted 3 lines
Quoted 1 line
Signed-off-by Akira Yokosawa <[email protected]>Applied and pushed, thank you!
So, looks like you are almost ready for the upcoming release. I'm preparing a patch to add a make target to move table captions to the top throughout perfbook.
Would you like to see such a patch before the upcoming release?
That would be very good!
Quoted 4 lines
And I have a reminder for you.
You might want to update the "Roadmap" section in Chapter 1 to mention new Chapter 15. Style Guide can be ignored for the moment.
Good catch, you know me too well! ;-)
I am also merging the "rt" chapter into the "advsync" chapter, but I do not believe that there are any tables there, so that should not conflict with your work.
Thanx, Paul
Quoted 9 lines
Thoughts?
Thanks, Akira
Quoted 3 lines
Thanx, Paul
[...]
Quoted 22 lines · Paul E. McKenney
Quoted 21 lines · Akira Yokosawa
Quoted 20 lines · Paul E. McKenney
Quoted 18 lines · Akira Yokosawa
Quoted 1 line
From
cf16d20dff9bf4cf2832c1fdd1fe00b39c4836fdMon Sep 17 00:00:00 2001From: Akira Yokosawa <[email protected]>
Date: Fri, 20 Oct 2017 07:16:48 +0900
Subject: [PATCH] styleguide: Reflect recent conversion of code snippets to listingAlso use a different approach to reduce skips of table captions. By setting a smaller value to \abovecaptionskip, captions of tables and figures can be made closer to the body regardless of their positions and avoid ambiguity of them to look like captions to other nearby tables/figures.
In the experimental tables, a negative value is still set to \abovetopsep to further reduce the skips.
As options of \captionsetup{} related to vertical spacing are ignored in captions controlled by the "float" package, remove them.
Signed-off-by Akira Yokosawa <[email protected]>
Quoted 8 lines
Quoted 6 lines
Quoted 1 line
Applied and pushed, thank you!
So, looks like you are almost ready for the upcoming release. I'm preparing a patch to add a make target to move table captions to the top throughout perfbook.
Would you like to see such a patch before the upcoming release?That would be very good!
It should be ready in a few days.
Quoted 11 lines
Quoted 5 lines
And I have a reminder for you.
You might want to update the "Roadmap" section in Chapter 1 to mention new Chapter 15. Style Guide can be ignored for the moment.
Good catch, you know me too well! ;-)
I am also merging the "rt" chapter into the "advsync" chapter, but I do not believe that there are any tables there, so that should not conflict with your work.
The change will involve only Makefile, perfbook.tex, and styleguide.tex. So there won't be any conflict.
And I'm sending a couple of nitpick patches in a few minutes.
Thanks, Akira
Quoted 14 lines
Thanx, Paul
Quoted 9 lines
Thoughts?
Thanks, Akira
Quoted 3 lines
Thanx, Paul
[...]