From c6c44943769259dac9f94cb0c38c0562a619e876 Mon Sep 17 00:00:00 2001 From: Jean-Noel Avila Date: Tue, 24 Nov 2020 15:08:43 +0100 Subject: [PATCH 1/5] Introduce test of html and epub This is an indirect way of checking the structure of the book, the asciidoc syntax and the external links. --- Gemfile | 3 ++- Rakefile | 11 +++++++++++ book/03-git-branching/sections/workflows.asc | 2 +- book/04-git-server/sections/gitlab.asc | 2 +- book/06-github/sections/1-setting-up-account.asc | 6 +++--- book/06-github/sections/2-contributing.asc | 4 ++-- book/06-github/sections/3-maintaining.asc | 8 ++++---- book/08-customizing-git/sections/attributes.asc | 6 +++--- book/10-git-internals/sections/environment.asc | 4 ++-- .../sections/visualstudio.asc | 2 +- book/B-embedding-git/sections/dulwich.asc | 2 +- 11 files changed, 31 insertions(+), 19 deletions(-) diff --git a/Gemfile b/Gemfile index 866260794..f925fcbd7 100644 --- a/Gemfile +++ b/Gemfile @@ -12,4 +12,5 @@ gem 'asciidoctor-pdf', '1.5.3' gem 'coderay', '1.1.3' gem 'pygments.rb', '1.2.1' gem 'thread_safe', '0.3.6' -gem 'epubcheck', '3.0.1' +gem 'epubcheck-ruby' +gem 'html-proofer' diff --git a/Rakefile b/Rakefile index 0aff12e43..63c1dbd89 100644 --- a/Rakefile +++ b/Rakefile @@ -1,4 +1,11 @@ namespace :book do + def exec_or_raise(command) + puts `#{command}` + if (! $?.success?) + raise "'#{command}' failed" + end + end + desc 'build basic book formats' task :build do @@ -16,10 +23,14 @@ namespace :book do `bundle exec asciidoctor #{params} -a data-uri progit.asc` puts " -- HTML output at progit.html" + exec_or_raise('htmlproofer --check-html progit.html') + puts "Converting to EPub..." `bundle exec asciidoctor-epub3 #{params} progit.asc` puts " -- Epub output at progit.epub" + exec_or_raise('epubcheck progit.epub') + # Commented out the .mobi file creation because the kindlegen dependency is not available. # For more information on this see: #1496. # This is a (hopefully) temporary fix until upstream asciidoctor-epub3 is fixed and we can offer .mobi files again. diff --git a/book/03-git-branching/sections/workflows.asc b/book/03-git-branching/sections/workflows.asc index b2063a827..9442b5680 100644 --- a/book/03-git-branching/sections/workflows.asc +++ b/book/03-git-branching/sections/workflows.asc @@ -23,7 +23,7 @@ It's generally easier to think about them as work silos, where sets of commits g [[lrbranch_b]] .A "`silo`" view of progressive-stability branching -image::images/lr-branches-2.png[A "`silo`" view of progressive-stability branching] +image::images/lr-branches-2.png[A “silo” view of progressive-stability branching'] You can keep doing this for several levels of stability. Some larger projects also have a `proposed` or `pu` (proposed updates) branch that has integrated branches that may not be ready to go into the `next` or `master` branch. diff --git a/book/04-git-server/sections/gitlab.asc b/book/04-git-server/sections/gitlab.asc index d81f60b46..ae2edc3a5 100644 --- a/book/04-git-server/sections/gitlab.asc +++ b/book/04-git-server/sections/gitlab.asc @@ -30,7 +30,7 @@ After you've logged in, click the "`Admin area`" icon in the menu at the top rig [[gitlab_menu]] .The "`Admin area`" item in the GitLab menu -image::images/gitlab-menu.png[The `"Admin area`" item in the GitLab menu] +image::images/gitlab-menu.png[The “Admin area” item in the GitLab menu] ===== Users diff --git a/book/06-github/sections/1-setting-up-account.asc b/book/06-github/sections/1-setting-up-account.asc index 6380420de..76a12a122 100644 --- a/book/06-github/sections/1-setting-up-account.asc +++ b/book/06-github/sections/1-setting-up-account.asc @@ -33,12 +33,12 @@ If you don't already have one, see <>. Open up your account settings using the link at the top-right of the window: .The "`Account settings`" link -image::images/account-settings.png[The "`Account settings`" link] +image::images/account-settings.png[The “Account settings” link] Then select the "`SSH keys`" section along the left-hand side. .The "`SSH keys`" link. -image::images/ssh-keys.png[The "`SSH keys`" link] +image::images/ssh-keys.png[The “SSH keys” link] From there, click the "`Add an SSH key`" button, give your key a name, paste the contents of your `~/.ssh/id_rsa.pub` (or whatever you named it) public-key file into the text area, and click "`Add key`". @@ -55,7 +55,7 @@ Next, if you wish, you can replace the avatar that is generated for you with an First go to the "`Profile`" tab (above the SSH Keys tab) and click "`Upload new picture`". .The "`Profile`" link -image::images/your-profile.png[The "`Profile`" link] +image::images/your-profile.png[The “Profile” link] We'll choose a copy of the Git logo that is on our hard drive and then we get a chance to crop it. diff --git a/book/06-github/sections/2-contributing.asc b/book/06-github/sections/2-contributing.asc index 67f1e2e67..e7aa71e98 100644 --- a/book/06-github/sections/2-contributing.asc +++ b/book/06-github/sections/2-contributing.asc @@ -21,7 +21,7 @@ This opens up a discussion thread with code review, and the owner and the contri To fork a project, visit the project page and click the "`Fork`" button at the top-right of the page. .The "`Fork`" button -image::images/forkbutton.png[The "`Fork`" button] +image::images/forkbutton.png[The “Fork” button] After a few seconds, you'll be taken to your new project page, with your own writeable copy of the code. @@ -123,7 +123,7 @@ To https://github.com/tonychacon/blink Now if we go back to our fork on GitHub, we can see that GitHub noticed that we pushed a new topic branch up and presents us with a big green button to check out our changes and open a Pull Request to the original project. -You can alternatively go to the "`Branches`" page at `https://github.com///branches` to locate your branch and open a new Pull Request from there. +You can alternatively go to the "`Branches`" page at `\https://github.com///branches` to locate your branch and open a new Pull Request from there. .Pull Request button image::images/blink-02-pr.png[Pull Request button] diff --git a/book/06-github/sections/3-maintaining.asc b/book/06-github/sections/3-maintaining.asc index 8767ec31e..a73a545c8 100644 --- a/book/06-github/sections/3-maintaining.asc +++ b/book/06-github/sections/3-maintaining.asc @@ -9,16 +9,16 @@ Let's create a new repository to share our project code with. Start by clicking the "`New repository`" button on the right-hand side of the dashboard, or from the `+` button in the top toolbar next to your username as seen in <<_new_repo_dropdown>>. .The "`Your repositories`" area -image::images/newrepo.png[The "`Your repositories`" area] +image::images/newrepo.png[The “Your repositories” area] [[_new_repo_dropdown]] .The "`New repository`" dropdown -image::images/new-repo.png[The "`new repository`" dropdown] +image::images/new-repo.png[The “new repository” dropdown] This takes you to the "`new repository`" form: .The "`new repository`" form -image::images/newrepoform.png[The "`new repository`" form] +image::images/newrepoform.png[The “new repository” form] All you really have to do here is provide a project name; the rest of the fields are completely optional. For now, just click the "`Create Repository`" button, and boom – you have a new repository on GitHub, named `/`. @@ -27,7 +27,7 @@ Since you have no code there yet, GitHub will show you instructions for how to c We won't belabor this here; if you need a refresher, check out <>. Now that your project is hosted on GitHub, you can give the URL to anyone you want to share your project with. -Every project on GitHub is accessible over HTTPS as `https://github.com//`, and over SSH as `git@github.com:/`. +Every project on GitHub is accessible over HTTPS as `\https://github.com//`, and over SSH as `\git@github.com:/`. Git can fetch from and push to both of these URLs, but they are access-controlled based on the credentials of the user connecting to them. [NOTE] diff --git a/book/08-customizing-git/sections/attributes.asc b/book/08-customizing-git/sections/attributes.asc index c4ec16b84..2c3000a20 100644 --- a/book/08-customizing-git/sections/attributes.asc +++ b/book/08-customizing-git/sections/attributes.asc @@ -198,14 +198,14 @@ These filters can be set to do all sorts of fun things. [[filters_a]] .The "`smudge`" filter is run on checkout -image::images/smudge.png[The "`smudge`" filter is run on checkout] +image::images/smudge.png[The “smudge” filter is run on checkout] [[filters_b]] .The "`clean`" filter is run when files are staged -image::images/clean.png[The "`clean`" filter is run when files are staged] +image::images/clean.png[The “clean” filter is run when files are staged] The original commit message for this feature gives a simple example of running all your C source code through the `indent` program before committing. -You can set it up by setting the filter attribute in your `.gitattributes` file to filter `*.c` files with the "`indent`" filter: +You can set it up by setting the filter attribute in your `.gitattributes` file to filter `\*.c` files with the "`indent`" filter: [source,ini] ---- diff --git a/book/10-git-internals/sections/environment.asc b/book/10-git-internals/sections/environment.asc index fc7e51d1b..1eab01fe2 100644 --- a/book/10-git-internals/sections/environment.asc +++ b/book/10-git-internals/sections/environment.asc @@ -55,8 +55,8 @@ A "`pathspec`" refers to how you specify paths to things in Git, including the u These are used in the `.gitignore` file, but also on the command-line (`git add *.c`). *`GIT_GLOB_PATHSPECS`* and *`GIT_NOGLOB_PATHSPECS`* control the default behavior of wildcards in pathspecs. -If `GIT_GLOB_PATHSPECS` is set to 1, wildcard characters act as wildcards (which is the default); if `GIT_NOGLOB_PATHSPECS` is set to 1, wildcard characters only match themselves, meaning something like `*.c` would only match a file _named_ "`*.c`", rather than any file whose name ends with `.c`. -You can override this in individual cases by starting the pathspec with `:(glob)` or `:(literal)`, as in `:(glob)*.c`. +If `GIT_GLOB_PATHSPECS` is set to 1, wildcard characters act as wildcards (which is the default); if `GIT_NOGLOB_PATHSPECS` is set to 1, wildcard characters only match themselves, meaning something like `\*.c` would only match a file _named_ "`\*.c`", rather than any file whose name ends with `.c`. +You can override this in individual cases by starting the pathspec with `:(glob)` or `:(literal)`, as in `:(glob)\*.c`. *`GIT_LITERAL_PATHSPECS`* disables both of the above behaviors; no wildcard characters will work, and the override prefixes are disabled as well. diff --git a/book/A-git-in-other-environments/sections/visualstudio.asc b/book/A-git-in-other-environments/sections/visualstudio.asc index c0ba8e582..c369e5132 100644 --- a/book/A-git-in-other-environments/sections/visualstudio.asc +++ b/book/A-git-in-other-environments/sections/visualstudio.asc @@ -18,7 +18,7 @@ This is a hub for performing Git actions; when you're _writing_ code, you'll pro [[vs_home]] .The "Home" view for a Git repository in Visual Studio -image::images/vs-2.png[The "`Home`" view for a Git repository in Visual Studio] +image::images/vs-2.png[The “Home” view for a Git repository in Visual Studio] Visual Studio now has a powerful task-focused UI for Git. It includes a linear history view, a diff viewer, remote commands, and many other capabilities. diff --git a/book/B-embedding-git/sections/dulwich.asc b/book/B-embedding-git/sections/dulwich.asc index 73e052bd0..49bef77d8 100644 --- a/book/B-embedding-git/sections/dulwich.asc +++ b/book/B-embedding-git/sections/dulwich.asc @@ -40,5 +40,5 @@ porcelain.log('.', max_entries=1) ==== Further Reading - * The official API documentation is available at https://www.dulwich.io/apidocs/dulwich.html[]. + * The official API documentation is available at https://www.dulwich.io/docs/api/ * Official tutorial at https://www.dulwich.io/docs/tutorial[] has many examples of how to do specific tasks with Dulwich. From 27dee631f4feec60b1f7a9f9d7e84af50341c0ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Date: Tue, 24 Nov 2020 19:21:45 +0100 Subject: [PATCH 2/5] Update Gemfile Co-authored-by: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> --- Gemfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Gemfile b/Gemfile index f925fcbd7..0a386382c 100644 --- a/Gemfile +++ b/Gemfile @@ -12,5 +12,5 @@ gem 'asciidoctor-pdf', '1.5.3' gem 'coderay', '1.1.3' gem 'pygments.rb', '1.2.1' gem 'thread_safe', '0.3.6' -gem 'epubcheck-ruby' -gem 'html-proofer' +gem 'epubcheck-ruby', '4.2.4.0' +gem 'html-proofer', '3.17.2' From ed8b8caa56dbb5b37ab24fb86a2101fc2a74602a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Date: Tue, 24 Nov 2020 22:29:08 +0100 Subject: [PATCH 3/5] Finish fixing errors --- book/06-github/sections/4-managing-organization.asc | 2 +- book/09-git-and-other-scms/sections/client-svn.asc | 2 +- book/A-git-in-other-environments/sections/guis.asc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/book/06-github/sections/4-managing-organization.asc b/book/06-github/sections/4-managing-organization.asc index 35cc312d1..cdb2447ab 100644 --- a/book/06-github/sections/4-managing-organization.asc +++ b/book/06-github/sections/4-managing-organization.asc @@ -12,7 +12,7 @@ Normally these accounts are used for Open Source groups (such as "`perl`" or "`r An organization is pretty easy to create; just click on the "`+`" icon at the top-right of any GitHub page, and select "`New organization`" from the menu. .The "`New organization`" menu item -image::images/neworg.png[The "`New organization`" menu item] +image::images/neworg.png[The “New organization” menu item] First you'll need to name your organization and provide an email address for a main point of contact for the group. Then you can invite other users to be co-owners of the account if you want to. diff --git a/book/09-git-and-other-scms/sections/client-svn.asc b/book/09-git-and-other-scms/sections/client-svn.asc index cb50aa59c..502e49982 100644 --- a/book/09-git-and-other-scms/sections/client-svn.asc +++ b/book/09-git-and-other-scms/sections/client-svn.asc @@ -78,7 +78,7 @@ Subversion has to clone one revision at a time and then push it back into anothe Now that you have a Subversion repository to which you have write access, you can go through a typical workflow. You'll start with the `git svn clone` command, which imports an entire Subversion repository into a local Git repository. -Remember that if you're importing from a real hosted Subversion repository, you should replace the `file:///tmp/test-svn` here with the URL of your Subversion repository: +Remember that if you're importing from a real hosted Subversion repository, you should replace the `\file:///tmp/test-svn` here with the URL of your Subversion repository: [source,console] ---- diff --git a/book/A-git-in-other-environments/sections/guis.asc b/book/A-git-in-other-environments/sections/guis.asc index 156ed6afa..c4d06d1e2 100644 --- a/book/A-git-in-other-environments/sections/guis.asc +++ b/book/A-git-in-other-environments/sections/guis.asc @@ -117,7 +117,7 @@ Branch management is one of the areas where the two tools diverge. On macOS, there's a button at the top of the window for creating a new branch: ."`Create Branch`" button on macOS -image::images/branch_widget_mac.png["`Create Branch`" button on macOS] +image::images/branch_widget_mac.png[“Create Branch” button on macOS] On Windows, this is done by typing the new branch's name in the branch-switching widget: From 2979f59468073587f7d69670e6d047c5092ac433 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Date: Wed, 25 Nov 2020 22:21:07 +0100 Subject: [PATCH 4/5] Remove a remaining trailing quote --- book/03-git-branching/sections/workflows.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/03-git-branching/sections/workflows.asc b/book/03-git-branching/sections/workflows.asc index 9442b5680..9e6f3922a 100644 --- a/book/03-git-branching/sections/workflows.asc +++ b/book/03-git-branching/sections/workflows.asc @@ -23,7 +23,7 @@ It's generally easier to think about them as work silos, where sets of commits g [[lrbranch_b]] .A "`silo`" view of progressive-stability branching -image::images/lr-branches-2.png[A “silo” view of progressive-stability branching'] +image::images/lr-branches-2.png[A “silo” view of progressive-stability branching] You can keep doing this for several levels of stability. Some larger projects also have a `proposed` or `pu` (proposed updates) branch that has integrated branches that may not be ready to go into the `next` or `master` branch. From 1a7c941584e824de15d875e10cbf1252638e6d69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= Date: Wed, 25 Nov 2020 22:25:27 +0100 Subject: [PATCH 5/5] convert autolink into url macro This allows to add the final period. --- book/B-embedding-git/sections/dulwich.asc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/B-embedding-git/sections/dulwich.asc b/book/B-embedding-git/sections/dulwich.asc index 49bef77d8..90ff4a05a 100644 --- a/book/B-embedding-git/sections/dulwich.asc +++ b/book/B-embedding-git/sections/dulwich.asc @@ -40,5 +40,5 @@ porcelain.log('.', max_entries=1) ==== Further Reading - * The official API documentation is available at https://www.dulwich.io/docs/api/ + * The official API documentation is available at https://www.dulwich.io/docs/api/[]. * Official tutorial at https://www.dulwich.io/docs/tutorial[] has many examples of how to do specific tasks with Dulwich.