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.)
> > 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
