Skip to content

Introduction is missing in v2.1.35 pdf #977

Open

Description

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

Activity

  1. jnavila commented on Feb 9, 2018

    @jnavila
    Member

    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?

  2. rahrah commented on Feb 9, 2018

    @rahrah
    Contributor

    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!

  3. ben commented on Feb 11, 2018

    @ben
    Member

    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.

  4. jnavila commented on Feb 11, 2018

    @jnavila
    Member

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

  5. rahrah commented on Feb 12, 2018

    @rahrah
    Contributor

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

  6. ben commented on Feb 13, 2018

    @ben
    Member

    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.

  7. jnavila commented on Feb 13, 2018

    @jnavila
    Member

    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.

  8. rahrah commented on Feb 20, 2018

    @rahrah
    Contributor

    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

  9. jnavila commented on Feb 20, 2018

    @jnavila
    Member

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

  10. rahrah commented on Feb 20, 2018

    @rahrah
    Contributor

    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.

  11. jnavila commented on Feb 20, 2018

    @jnavila
    Member

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

  12. ghost added a commit that references this issue on Apr 24, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions