On Thu, Aug 03, 2017 at 07:22:07AM +0900, Akira Yokosawa wrote:
> On 2017/08/02 09:29:10 -0700, Paul E. McKenney wrote:
> > On Wed, Aug 02, 2017 at 11:57:33PM +0900, Akira Yokosawa wrote:
> >> On 2017/08/01 13:40:47 -0700, Paul E. McKenney wrote:
> >>> On Mon, Jul 31, 2017 at 11:43:41PM +0900, Akira Yokosawa wrote:
> >>>> >From e35b5bc0c56f255caee91054f05a5dd7b824b5fa Mon Sep 17 00:00:00 2001
> >>>> From: Akira Yokosawa <akiyks@xxxxxxxxx>
> >>>> Date: Mon, 31 Jul 2017 23:20:57 +0900
> >>>> Subject: [PATCH v2 0/8] Add style guide
> >>>>
> >>>> Hi Paul,
> >>>>
> >>>> This is the respin I mentioned earlier.
> >>>> Patch #2 has a few more changes from v1 to modify strings of package name.
> >>>> Other than that, the end result should be the same as v1.
> >>>
> >>> Having a style guide is very good -- for one thing, it allows me to
> >>> copy and paste from a uniform set of examples as opposed to whatever
> >>> example happens to be at hand. ;-)
> >>>
> >>> So thank you very much!!!
> >>
> >> Glad to know you like it!
> >>
> >>>> Note on the status of the floatrow package:
> >>>>
> >>>> Current version v0.3b was revised 2009/08/02.
> >>>> There has been no update since.
> >>>> I'm not sure if upstreaming is possible.
> >>>
> >>> If we have to maintain our own, so it goes.
> >>>
> >>> The missing two patches eventually showed up, so I applied them.
> >>>
> >>> Some comments:
> >>>
> >>> o I have misgivings about thin spaces instead of commas for
> >>> numbers. I do understand the concern, given that many of our
> >>> European readers are used to 1.234.567,89 instead of 1,234,567.89.
> >>> My problem is that the NIST convention sounds like one of those
> >>> compromises that makes things worse for everyone.
> >>>
> >>> But let's see what I think in a year or two.
> >>
> >> Maybe in another decade??? ;-)
> >
> > Hey, a decade is less than 20% of my lifespan thus far. ;-)
> >
> >>> o I don't have an objection to the NIST percent convention.
> >>> Let's face it, the percent character is a pain in LaTeX
> >>> no matter what. ;-)
> >>>
> >>> o I would definitely consider patches to improve the math.
> >>>
> >>> o I like the idea of autonumbering, but not if it requires
> >>> the code being in separate files.
> >>
> >> No, separate files are not required.
> >> The LaTeX source of the code snippet cannot be embedded in \verbbox{}
> >> because of the LaTeX commands therein, but \verbbox{} of C sources can
> >> have the same option as the \verbfilebox{}.
> >> By defining the option as a macro, it would be easier to convert to
> >> auto-numbering scheme.
> >
> > The main value is not the auto-numbering, given that I have to do
> > tab-to-space conversion anyway, and I have one script that does both.
> > (See utilities/c2latex.sh and utilities/latex2c.sh.) Though I do admit
> > that auto-numbering would make trivial edits easier.
> >
> > The win is the prettier format.
> >
> >> Now, I have toyed with
> >>> the idea of automatically extracting the code from the
> >>> CodeSamples directory, but haven't yet come up with anything
> >>> satisfactory.
> >>
> >> Besides the adjustment of indentation, there need to be some way to
> >> specify the part of the code you want to include as a code snippet.
> >
> > And it might or might not be worth it. It has not been worth it thus
> > far, but who knows?
> >
> >>> The automation would probably make for more failures to
> >>> update line-number references in the text, but then again
> >>> that sometimes happens with the current arrangements.
> >>>
> >>> o I am not all that much a fan of captions at the tops of tables,
> >>> but it is a very common convention, so I will accept patches
> >>> converting tables to that format.
> >>
> >> Position of captions can be specified in perfbook.tex for each type of float.
> >> So it should be easy to choose a layout of your choice without any
> >> modification of the source of tables, similar to the monospace font choice.
> >
> > OK, even better!
> >
> >>> o The ruled code (as in Listings D.3, D.4, and D.5) does look nice.
> >>> Listing D.2 looks quite strange to me. I would be happy to
> >>> accept patches to make the listings look like Listing D.3.
> >>
> >> Before such style adjustment, we need to convert those code snippets
> >> to the "listings" environment. It will involve changes of label names and
> >> its references, and the citing words "Figure" need to be changed to "Listing".
> >>
> >> Those changes would be larger than the conversion from verbatim to verbbox.
> >
> > Maybe chapter by chapter? Your suggestion of starting with the litmus
> > tests in the updated memory-barriers section sounds good. (And yes,
> > I have been stalled by other work, but will be on this no later than
> > the week of August 21st.)
>
> My suggestion was to employ auto-numbering there, but do you also want
> the conversion to "listings" environment with the "ruled" appearance at
> the same time?
> That would cause inconsistency in the upcoming release, I'm afraid.
>
> Well, litmus tests are special and new look only for them might be OK.
> I can prepare trial patches; one for auto-numbering, another for the
> "ruled" appearance.
>
> Would this work for you?
That actually sounds like a very good plan -- new format for litmus
tests, and the code remains the same. Perhaps the contrast will
elicit feedback.
Besides, this is a release, not a full-fledged edition. For an edition,
we would want a higher degree of consistency. ;-)
Thanx, Paul
> Thanks, Akira
>
> >
> >>> o In https://www.inf.ethz.ch/personal/markusp/teaching/guides/guide-tables.pdf,
> >>> I find the examples from The Economist to be much more attractive
> >>> than his example tables. Not sure whether LaTeX is up to all
> >>> that without excessive formatting pain, though. ;-)
> >>>
> >>> If it is easy to do, it would be interesting to see what
> >>> Table D.2 would look like with The-Economist-style dashed
> >>> lines between the rows.
> >>
> >> There is a package named "arydshln". It provides dashed rules for tables.
> >> But it conflicts with "tabulary" package. I'll see what I can.
> >
> > Ouch! Well, at least a package exists, I suppose.
> >
> >>> o Putting related code side by side as in Listings D.4 and D.5
> >>> could be quite useful. I did this manually in a few places,
> >>> for example, Figures 9.38-9.40. Maybe these would look better
> >>> as floatrows.
> >>>
> >>> And the comment at the end:
> >>>
> >>> % Capitalize initialism:
> >>> % Gnu Compiler Collection = GCC
> >>> % gcc should be used as a command name in \co{gcc}
> >>> % When mentioning GCC's C language, use `GNU C'
> >>>
> >>> I have been rather random here, and it would be good to have a
> >>> standard. The one above looks fine to me.
> >>>
> >>> % Trademarks:
> >>> % As the Legal page covers trademarks, there is no need to
> >>> % use trademark symbol in the text. They seems to have been
> >>> % imported from original publications.
> >>>
> >>> Indeed they have!
> >>>
> >>> % Power or POWER?
> >>> % IBM's trademark page at https://www.ibm.com/legal/us/en/copytrade.shtml#section-P
> >>> % lists the following.
> >>> % PowerPC
> >>> % Power Architecture
> >>> % Power
> >>> % POWER
> >>> % POWER5
> >>> % POWER6
> >>> %
> >>> % not Power5, POWER 5, nor Power-5
> >>>
> >>> IBM's preferences have changed over time, so I end up importing
> >>> whatever was the style at the time of publication. :-/
> >>>
> >>> Again, consistency would be good, but IBM's preferences are likely
> >>> to continue to change over time.
> >>>
> >>> What would you suggest?
> >>
> >> What about defining a macro named "\Power{}", which can be used like
> >> \Power{5} in the source code? If IBM's preference changes, we can
> >> change the definition accordingly.
> >
> > The definition might end up with special cases over time, but better than
> > massive repeated rounds of search-and-replace. ;-)
> >
> >>> % Ugly line break by \co{}
> >>> % __
> >>> % atomic_store()
> >>> %
> >>> % seqlock_
> >>> % t
> >>> %
> >>> % Is there any way to prevent these breaks?
> >>> % Maybe we need an on-the-fly script to convert such \co{}s
> >>> % to couples of \co{}s.
> >>> % Example:
> >>> % \co{__atomic_store()} -> \co{__}\co{atomic_store()}
> >>> % \co{seqlock_t} -> \co{seqlock_}\co{t}
> >>>
> >>> As long as it is automated! ;-)
> >>>
> >>> Overall, my main goal here is making the book more attractive and
> >>> easier to read -- not so much conventions for conventions sake.
> >>
> >> Yes, I think I understand.
> >>
> >> If I'm guessing right, you are in the middle of updating the memory
> >> barriers section.
> >> If the transition to auto-numbering helps in adding new code snippets,
> >> I can generate an example patch of a (say) litmus test.
> >>
> >> The other changes can wait after the upcoming release, I suppose.
> >
> > That sounds very good! I am hoping to release by the end of August or
> > September, FWIW.
> >
> > Thanx, Paul
> >
> >> Thanks, Akira
> >>
> >>>
> >>> Thanx, Paul
> >>>
> >>>> Thanks, Akira
> >>>> --
> >>>> Akira Yokosawa (8):
> >>>> Localize floatrow.sty as floatrowpf.sty
> >>>> Apply workaround to floatrowpf.sty
> >>>> Define 'listing' environment for style guide
> >>>> styleguide: Add listing environment examples
> >>>> Disable 'floatrow' layout in manually aligned code snippets
> >>>> styleguide: Add example of grouping code snippets
> >>>> styleguide: Add example of preferred table layout using 'booktabs'
> >>>> styleguide: Tweak layout of 'Limitation' table
> >>>>
> >>>> appendix/styleguide/hello.c | 9 +
> >>>> appendix/styleguide/styleguide.tex | 177 ++++-
> >>>> defer/rcuusage.tex | 6 +-
> >>>> floatrowpf.sty | 1482 ++++++++++++++++++++++++++++++++++++
> >>>> howto/howto.tex | 4 +-
> >>>> perfbook.tex | 4 +
> >>>> 6 files changed, 1668 insertions(+), 14 deletions(-)
> >>>> create mode 100644 appendix/styleguide/hello.c
> >>>> create mode 100644 floatrowpf.sty
> >>>>
> >>>> --
> >>>> 2.7.4
> >>>>
> >>>>
> >>>
> >>>
> >>
> >> --
> >> To unsubscribe from this list: send the line "unsubscribe perfbook" in
> >> the body of a message to majordomo@xxxxxxxxxxxxxxx
> >> More majordomo info at http://vger.kernel.org/majordomo-info.html
> >>
> >
> >
>
> --
> To unsubscribe from this list: send the line "unsubscribe perfbook" in
> the body of a message to majordomo@xxxxxxxxxxxxxxx
> More majordomo info at http://vger.kernel.org/majordomo-info.html
>
--
To unsubscribe from this list: send the line "unsubscribe perfbook" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
