Merge pull request #23 from vjousse/chore/update-english-version

Update english version

makedist.sh

@@ -24,7 +24,7 @@ cd ..
 cp rst/fr/_build/epub/Vimpourleshumains.epub dist/$ts/fr/vim-pour-les-humains.epub
 cp rst/fr/_build/latex/vimpourleshumains.pdf dist/$ts/fr/vim-pour-les-humains.pdf
 cp rst/en/_build/epub/Vimforhumans.epub dist/$ts/en/vim-for-humans.epub
-cp rst/en/_build/latex/Vimforhumans.pdf dist/$ts/en/vim-for-humans.pdf
+cp rst/en/_build/latex/vimforhumans.pdf dist/$ts/en/vim-for-humans.pdf
 cd dist/$ts
 
 # Create Kindle Versions

rst/en/Makefile

@@ -1,158 +1,23 @@
-# Makefile for Sphinx documentation
+# Minimal makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line.
-SPHINXOPTS    =
-SPHINXBUILD   = sphinx-build
-PAPER         =
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
 BUILDDIR      = _build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html       to make standalone HTML files"
-	@echo "  dirhtml    to make HTML files named index.html in directories"
-	@echo "  singlehtml to make a single large HTML file"
-	@echo "  pickle     to make pickle files"
-	@echo "  json       to make JSON files"
-	@echo "  htmlhelp   to make HTML files and a HTML help project"
-	@echo "  qthelp     to make HTML files and a qthelp project"
-	@echo "  devhelp    to make HTML files and a Devhelp project"
-	@echo "  epub       to make an epub"
-	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
-	@echo "  text       to make text files"
-	@echo "  man        to make manual pages"
-	@echo "  texinfo    to make Texinfo files"
-	@echo "  info       to make Texinfo files and run them through makeinfo"
-	@echo "  gettext    to make PO message catalogs"
-	@echo "  changes    to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck  to check all external links for integrity"
-	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
-
-clean:
-	-rm -rf $(BUILDDIR)/*
-
-html:
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-
-dirhtml:
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-
-singlehtml:
-	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
-	@echo
-	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-
-pickle:
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp:
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp:
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Vimpourleshumains.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Vimpourleshumains.qhc"
-
-devhelp:
-	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
-	@echo
-	@echo "Build finished."
-	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/Vimpourleshumains"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Vimpourleshumains"
-	@echo "# devhelp"
-
-epub:
-	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
-	@echo
-	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-
-latex:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make' in that directory to run these through (pdf)latex" \
-	      "(use \`make latexpdf' here to do that automatically)."
-
-latexpdf:
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo "Running LaTeX files through pdflatex..."
-	$(MAKE) -C $(BUILDDIR)/latex all-pdf
-	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-
-text:
-	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
-	@echo
-	@echo "Build finished. The text files are in $(BUILDDIR)/text."
-
-man:
-	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
-	@echo
-	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-
-texinfo:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo
-	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
-	@echo "Run \`make' in that directory to run these through makeinfo" \
-	      "(use \`make info' here to do that automatically)."
-
-info:
-	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
-	@echo "Running Texinfo files through makeinfo..."
-	make -C $(BUILDDIR)/texinfo info
-	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-
-gettext:
-	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
-	@echo
-	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
+.PHONY: help Makefile
 
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-pdf:
-	$(SPHINXBUILD) -b pdf $(ALLSPHINXOPTS) _build/pdf
-	@echo
-	@echo "Build finished. The PDF files are in _build/pdf."
+livehtml:
+	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

rst/en/_static/css/custom.css

@@ -0,0 +1,3 @@
+div.highlight pre {
+  background-color: #fdf6e3;
+}

rst/en/_templates/vimforhumans.sty

@@ -0,0 +1,15 @@
+% https://github.com/club-1/docs/blob/9c175ccd2dc4810d1dd4f9f0968128029bd5d3a2/_templates/club1.sty#L8-L18
+% Paquet LaTeX permettant de customiser le rendu du PDF.
+\ProvidesPackage{vimforhumans}[2024/05/08 LaTeX customizations for Vim for humans]
+
+% Définition de TwemojiMozilla comme police de substitution
+% pour pouvoir l'utiliser lorsque des caractères sont introuvables,
+% notamment lorsqu'il s'agit d'emojis.
+\directlua{
+	luaotfload.add_fallback("emoji", {"[TwemojiMozilla.ttf]:mode=harf"})
+}
+% Définition des polices du document,
+% en spécifiant la police de substitution.
+\setmainfont{LatinModernRoman}[RawFeature={fallback=emoji},SmallCapsFont={* Caps}]
+\setsansfont{LatinModernSans}[RawFeature={fallback=emoji}]
+\setmonofont{DejaVuSansMono}[RawFeature={fallback=emoji},Scale=0.8]

rst/en/conf.py

@@ -12,9 +12,9 @@
 
 
 # The short X.Y version.
-version = "1.0"
+version = "2.0"
 # The full version, including alpha/beta/rc tags.
-release = "1.0"
+release = "2.0"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -32,13 +32,20 @@
 html_theme = "alabaster"
 html_static_path = ["_static"]
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    "css/custom.css",
+]
+
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = "solarized-light"
 
 highlight_language = "vim"
 
 rst_prolog = """
 .. role:: vimcmd
+    :class: pre
 .. role:: viml(code)
    :language: vim
 """
@@ -62,6 +69,7 @@
 .. |tsharp| replace:: ``#``
 .. |tleader| replace:: ``<Leader>``
 .. |tcomma| replace:: ``,``
+.. |tquestion| replace:: ``?``
 .. |ta| replace:: ``a``
 .. |tA| replace:: ``A``
 .. |tb| replace:: ``b``
@@ -85,14 +93,17 @@
 .. |tO| replace:: ``O``
 .. |tp| replace:: ``p``
 .. |tP| replace:: ``P``
+.. |tq| replace:: ``q``
 .. |tu| replace:: ``u``
 .. |tr| replace:: ``r``
 .. |tv| replace:: ``v``
+.. |tV| replace:: ``V``
 .. |tw| replace:: ``w``
 .. |tx| replace:: ``x``
 .. |tX| replace:: ``X``
 .. |ty| replace:: ``y``
 .. |tyty| replace:: ``yy``
+.. |ttreturn| replace:: ``the backspace key``
 .. |ttc| replace:: the |tc| key
 .. |ttd| replace:: the |td| key
 .. |tte| replace:: the |te| key
@@ -106,10 +117,12 @@
 .. |tto| replace:: the |to| key
 .. |ttp| replace:: the |tp| key
 .. |ttP| replace:: the |tP| key
+.. |ttq| replace:: the |tq| key
 .. |ttm| replace:: the |tm| key
 .. |ttu| replace:: the |tu| key
 .. |ttr| replace:: the |tr| key
 .. |ttv| replace:: the |tv| key
+.. |ttV| replace:: the |tV| key
 .. |ttx| replace:: the |tx| key
 .. |tty| replace:: the |ty| key
 .. |ttw| replace:: the |tw| key
@@ -123,13 +136,44 @@
 .. |ttctrl| replace:: the |tctrl| key
 .. |ttslash| replace:: the |tslash| key
 .. |ttenter| replace:: the |tenter| key
+.. |ttquestion| replace:: the |tquestion| key
 """
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
-latex_documents = [
-    ("index", "Vimforhumans.tex", "Vim for humans", "Vincent Jousse", "manual"),
-]
+latex_engine = "lualatex"
+latex_additional_files = ["_templates/vimforhumans.sty"]
+
+
+# See https://tex.stackexchange.com/questions/616277/how-to-set-an-inline-tcbox-height-to-a-fixed-height-1em
+latex_custom = r"""
+\usepackage{vimforhumans}
+\usepackage[most]{tcolorbox}
+\makeatletter
+\newcommand\mystrut{\rule[0pt]{0pt}{0.6em}}
+\tcbset{on line,
+        boxsep=0pt, left=2pt,right=2pt,top=1pt,bottom=1pt,
+        colframe=white,colback=gray!20, fontupper={\ttfamily\mystrut}
+        }
+\let\OldSphinxcode\sphinxcode
+\renewcommand{\sphinxcode}[1]{\OldSphinxcode{\tcbox{#1}}}
+\makeatother
+"""
+
+
+latex_elements = {
+    # Always use A4 paper.
+    "papersize": "a4paper",
+    # Make sure to use babel instead of polyglossia.
+    "babel": r"\usepackage{babel}",
+    # Uniformization of chapter style, disable Sphinx default.
+    "fncychap": "",
+    # Use names for colors.
+    "passoptionstopackages": r"\PassOptionsToPackage{svgnames,table}{xcolor}",
+    # Clear default font config.
+    "fontpkg": "",
+    # Add custom preamble after 'hyperref' and 'sphinx'.
+    "preamble": latex_custom,
+    "sphinxsetup": "verbatimwithframe=true, VerbatimColor={RGB}{253,246,227}",
+}

rst/en/examples.rst

@@ -12,14 +12,14 @@ Questions / Answers
 How do I  quit |vim|?
 ---------------------
 
-First you need to be in normal mode. If you don't know if you are in normal mode, just press |ttesc| or |ttsemicolon| (depending on your configuration) multiple times. This should bring you to normal mode. Then, type :vimcmd:`:q` to exit |vim|. The problem is that most of the time, |vim| will not let you quit immediately. For example, if you have unsaved changes, |vim|  will not let you quit. You can cancel your modifications by using :vimcmd:`!` like this: :vimcmd:`:q!`. You can also save your modifications and save like this: :vimcmd:`:wq`.
+First you need to be in normal mode. If you don't know if you are in normal mode, just press |ttesc| or |ttsemicolon| (depending on your configuration) multiple times. This should bring you to normal mode. Then, type ``:q`` to exit |vim|. The problem is that most of the time, |vim| will not let you quit immediately. For example, if you have unsaved changes, |vim|  will not let you quit. You can cancel your modifications by using ``!`` like this: ``:q!``. You can also save your modifications and save like this: ``:wq``.
 
-How do I 'save as'?
+How do I "save as"?
 -------------------
 
-In normal mode, if you type :vimcmd:`:w`, |vim| will by default save your modifications into the current file. If you want to use another filename to "save as", you just need to specify it after :vimcmd:`w` like this: :vimcmd:`:w myfile.txt`. |vim| will save your file under the name *myfile.txt*. However, be aware that |vim| will not open *myfile.txt*, it will stay on the previous file.
+In normal mode, if you type ``:w``, |vim| will by default save your modifications into the current file. If you want to use another filename to "save as", you just need to specify it after ``w`` like this: ``:w myfile.txt``. |vim| will save your file under the name *myfile.txt*. However, be aware that |vim| will not open *myfile.txt*, it will stay on the previous file.
 
-If you want |vim| to save under the filename *myfile.txt* and then open the file in the current buffer, you will have to use :vimcmd:`:sav myfile.txt`.
+If you want |vim| to save under the filename *myfile.txt* and then open the file in the current buffer, you will have to use ``:sav myfile.txt``.
 
 How do I copy/cut and paste?
 ----------------------------
@@ -37,7 +37,7 @@ How do I create a new file?
 ---------------------------
 
 
-The traditional way to create a file is to type, in normal mode, :vimcmd:`:e myfile.txt` to open an empty buffer. Then, save your buffer using :vimcmd:`:w`. Il will be saved as ``myfile.txt`` in the current directory.
+The traditional way to create a file is to type, in normal mode, ``:e myfile.txt`` to open an empty buffer. Then, save your buffer using ``:w``. Il will be saved as ``myfile.txt`` in the current directory.
 
 You can also use Lusty Explorer (cf. :ref:`seclusty`). To do so, launch it using ``,lr`` or ``,lf`` (supposing that your leader key is ``,``), type the name of the file you want to create and then press |ttctrl| and |tte| at the same time. You can then save as above.
 
@@ -55,12 +55,12 @@ Files
 =================================================== ==================================== ============
 Expected result                                     Action                               Comments
 =================================================== ==================================== ============
-**Save**                                            :vimcmd:`:w`
-**Save as**                                         :vimcmd:`:w filename.txt`            Save as filename.txt but don't open filename.txt
-**Save as / open**                                  :vimcmd:`:sav filename.txt`          Save as and open filename.txt
-**Quit without saving (force quit)**                :vimcmd:`:q!`
-**Save and quit**                                   :vimcmd:`:wq`                        
-**Save as root**                                    :vimcmd:`:w !sudo tee %`             
+**Save**                                            ``:w``
+**Save as**                                         ``:w filename.txt``                  Save as filename.txt but don't open filename.txt
+**Save as / open**                                  ``:sav filename.txt``                Save as and open filename.txt
+**Quit without saving (force quit)**                ``:q!``
+**Save and quit**                                   ``:wq``                        
+**Save as root**                                    ``:w !sudo tee %``             
 =================================================== ==================================== ============
 
 Movement

rst/en/index.rst

@@ -18,13 +18,3 @@ Vim for humans
    text-manip
    plugins
    examples
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-