Rename "Getting Git on a Server" link to reflect the section name

[rpjday]

The original asciidoc link name displayed to the reader was
"Git on the Server", which is in fact the very name of the
chapter, which is somewhat confusing, so change the link name
to reflect the actual section name.

[ben]

Unfortunately, this won't do what you want it to. The anchor name could be "fkjldsafudiosa" and you'd still get "Git on the Server" as the link text. In the print version and when Atlas was doing the building it would put "Section X.Y: The Subtitle" in the link, but Asciidoctor doesn't do that, it seems to just pull the chapter name, so there's no fixing it.

[rpjday]

Uh, no, that's not what it does, it works just fine, at least in my PDF version, and you have that very thing in other places in the book. In Section 1, "basics.asc", you have a link to "<<_undoing>>", which properly displays the name of that section in Chapter 2, "Undoing Things". Not sure what you're seeing, but I actually checked the output of the above before submitting it and it seems fine.

[ben]

OK, let's give it a shot. We'll see what happens on git-scm.com.

[rpjday]

Just tested after fetching all the merged content upstream, and it looks good. Would this represent something that has changed with asciidoctor's behaviour?

[jnavila]

Hum, it turns out to not work so well....

[rpjday]

I thought Ben verified that this works just fine. What's the issue? Saying "it turns out to not work so well" is not particularly informative.

[jnavila]

True. In fact, asciidoctor already automatically assigns ids using the same algorithm. That creates warnings when compiling due to conflicts between hand-made and automatic ids. Now, it seems that the compilation of the book on git-scm is stuck to the version at this commit because that created some inconsistencies in the DB. See for instance the link in
https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository#_git_cloning

It's a bug in the code at git-scm, but anyway, this renaming is conflicting. I'm working on porting the structure of the book to the latest versions of asciidoctor for pdf and ebook generation and all these hand-made ids need to be renamed (https://github.com/progit/progit2-fr/tree/reorder_files) to avoid clashes with automatic names.

[ben]

What do we need to do on this repo to help out? Would it make sense to revert this, or keep moving forward?

[jnavila]

For git-scm, it's really a bug that needs to be fixed there. But you have to bear in mind that one output of the changes here is the publishing on git-scm.com, which makes some special processings. Changes here can trigger bugs there.

Then, for the rework, I need to set up the compilation script at git-scm.com to take into account the new structure of the files (basically, stop using atlas.json and really rely on progit.asc).

For this repo, I can propose the rework of the structure:

• move the first level chapters to the root the project, change theirs top ids and change their includes accordingly
• promote all the titles in the chapters and add the demoting sequence in progit.asc
• change all ids and xrefs. I just added an 's' before them. for the xref, adding the top chapter is needed <<chapter-id#id>>

All this is explained at https://github.com/asciidoctor/asciidoctor-epub3#structuring-your-manuscript