Introduction is missing in v2.1.35 pdf

[monk-time]

I was comparing an old copy of the book with the latest PDF, and the first thing I saw was that the introduction with short summaries of each chapter is missing. It's in the repo (book/introduction.asc) but not in the pdf.

[jnavila]

The atlas.json file included a lot more than what we build from progit.asc:

• book/cover.html,
• LICENSE.asc,
• book/preface.asc,
• book/contributors.asc,
• book/introduction.asc

Does it make more sense to add these files to the book now?

[rahrah]

Not so sure this is a vote, but I'd vote for putting the introduction, back in. It does probably need xrefs to the chapters to which it refers, and the removal of non ascii punctuation, esp., apostrophes, but it was part of the original book. It adds to the informal tone of the book which might get lost with the many small stylistic changes which have happened in the last few months (for example fd25777 (it's not my intention to negatively criticise that commit or commits like it, just to comment on small changes in style and voice that over time can change the global tone.)).

There's a more general point.

In what general direction do a mass of small, stylistic changes move the book?

Is the idea, here, to have an evolving book? Should it be open to big changes from community contributors, keeping up with changes in git, and ever striving for better expression and utility? Or should it keep the original book's content, voice and style, where changes are limited to small corrections, clarifications or errata? Or both? I know this is covered in CONTRIBUTING.md, but the issue does seem to be a little muddy.

Sorry for lack of brevity!

[ben]

Is the idea, here, to have an evolving book?

Yes! Our goal from the start was to make a great resource for the Git community, and we knew we couldn't do it alone. It's true that accepting contributions will shift the tone and focus a bit, but that's why I'm here, to watch out for huge directional changes, and guide the smaller ones. We don't lay this philosophy out anywhere in the docs, but for the average contributor who just wants to clear up a confusing pair of sentences it doesn't really matter.

On the topic of including the introduction, I vote yes, let's build it into every edition.

[jnavila]

What about the other files? The preface is already included.

[rahrah]

@ben That's great to hear!!!!

[ben]

I think we should aim to include everything that's in the print version as long as it makes sense.

• Cover: ebooks should have a cover image
• License: this seems appropriate
• Contributors: this is one of the few perks I can offer in exchange for contributions, it'd be good to include it, especially if it's up-to-date
• Introduction: we just talked about this

I believe the PDF version includes the index, but I don't think the ebook versions do. It sure would be nice. The tags are embedded in the text, it might just be an asciidoctor flag.

[jnavila]

As of now:

• all versions of the book already use the cover
• integrating the license is quite straightforward
• The contributors' list... Well, I don't know how it was built in the first place. To be pedantic, it should be built dynamically in the C.I. phase. There's also some page layout work on this.
• introduction. No problem. Just need to work out heading levels with the preface so that the generation both works in pdf et epub.

And still, the need to cross check that the publication on git-scm is not broken.

[rahrah]

Commit 154e00f introduced this to the Rakefile:

git shortlog -s --all| grep -v -E "(Straub|Chacon)" | cut -f 2- | column -c 120 > book/contributors.txt

Might I suggest that this would be better:

git shortlog -s master | grep -v -E "(Straub|Chacon)" | cut -f 2- | column -c 120 > book/contributors.txt

dropping the --all

My repo contains my personal branches, and I don't want accidentally distribute stuff with false attributions!

Also the pdf on git-scm.org and my builds don't render authors correctly:

Velocet@... in commit: a8f68d1
dilu.kxq@... in commit: 05a489e

[jnavila]

Ok for master. What do you mean by "don't render authors correctly"?

[rahrah]

The last two users at the bottom of the third column of the contributors' list in:

https://github.com/progit/progit2/releases/download/2.1.39/progit.pdf

have issues:

The penultimate user, Velocet should be:

ᐯᕮᒪᗝᑕᕮᒣ

142F CANADIAN SYLLABICS PE
156E CANADIAN SYLLABICS TTHA
14AA CANADIAN SYLLABICS MA
15DD CANADIAN SYLLABICS CARRIER THO
1455 CANADIAN SYLLABICS TA
156E CANADIAN SYLLABICS TTHA
14A3 CANADIAN SYLLABICS ME

See:

https://r12a.github.io/uniview/?charlist=%E1%90%AF%E1%95%AE%E1%92%AA%E1%97%9D%E1%91%95%E1%95%AE%E1%92%A3

Unicode block: Unified Canadian Aboriginal Syllabics

The final user should be:

狄卢

72C4 [CJK Unified Ideographs]
5362 [CJK Unified Ideographs]

See:
https://r12a.github.io/uniview/?charlist=%E7%8B%84%E5%8D%A2

but only the first character appears

狄

in the pdf.

I know it's a small point, but to the authors.... Also, perhaps there should be a policy for encodings
of names. I certainly don't know enough about unicode enabled fonts to even suggest a solution to this one.

[jnavila]

Ah, we don't embed all the fonts needed in the PDF. Strangely, asciidoctor does not complain.