.. _2024-name:

!!!!
2024
!!!!

.. meta::
  :keywords: 2024,xrst,release,notes,for,mm-dd,12-28,12-10,12-09,12-08,12-01,11-30,11-27,10-25,10-01,09-09,08-25,08-13,08-12,06-25,04-30,04-06,04-05,03-30,03-29,03-28,03-19,03-16,03-04,03-02,03-01,02-29,02-25,02-14,02-03,01-29,01-21,01-04,01-01

.. index:: 2024, xrst, release, notes, 2024

.. _2024-title:

xrst Release Notes for 2024
###########################

.. contents::
  :local:

.. index:: mm-dd

.. _2024@mm-dd:

mm-dd
*****

.. _2024@mm-dd@12-28:

12-28
=====
#. Make some minor edits to the :ref:`purpose-name` page.
   In particular, the following text was added:
   once you learn xrst, you can use it for any source code language.
#. Improve the discussion of how the template command differs from an
   :ref:`template_cmd@Rst Include` .

.. _2024@mm-dd@12-10:

12-10
=====
Add space below template file name, to better separate arguments,
in the second xrst template command in :ref:`template_example-name` .

.. _2024@mm-dd@12-09:

12-09
=====
Correct comment about the example
:ref:`config_file@directory@project_directory` .
To be specific, it is relative to where the
:ref:`run_xrst@config_file` is located
(which may not be the directory where xrst is run).

.. _2024@mm-dd@12-08:

12-08
=====
The suspend comment :ref:`suspend_cmd@left, right` syntax was extended
from just the ``!=`` operator to include the ``==`` operator.
In addition, white space is now forbidden in the
*left* and *right* operands.

.. _2024@mm-dd@12-01:

12-01
=====
Include the contents of the
ref:`template files <template_cmd@template_file>` that are used
below the source for each page.

.. _2024@mm-dd@11-30:

11-30
=====
Comment lines were added to the template command; see
:ref:`template_cmd@comment` .
Also fix some error messaging in the template command.

.. _2024@mm-dd@11-27:

11-27
=====
The :ref:`suspend_cmd@left, right` syntax was added to the suspend command.
This makes it easier to use the suspend command inside of a
:ref:`template_cmd@template_file` .
The example :ref:`template file <example_expansion_one@This Template File>`
was changed to use the left, right syntax
instead of the :ref:`suspend_cmd@boolean` syntax.

.. _2024@mm-dd@10-25:

10-25
=====
Spelling errors that occurred inside a
:ref:`template_cmd@template_file`
were reported using the line number in the template file
and the file name for the :ref:`begin_cmd@Page File` .
This has been fixed so that the template_file, template_line,
page_file, and page_line are all reported.

.. _2024@mm-dd@10-01:

10-01
=====
MacOS python has an issue that was causing xrst to abort; see
`urllib3 issue 3020 <https://github.com/urllib3/urllib3/issues/3020>`_ .
This has been changed so that xrst only prints a warning
when this is the only warning or error message.

.. _2024@mm-dd@09-09:

09-09
=====
The development and install tools were extended to work well on
MacOS with homebrew.
The versions between 08-25 and 09-08
were not tested and may have trouble on other systems.
(There was a problem with the new ``bin/grep_and_sed.sh`` script.)

.. _2024@mm-dd@08-25:

08-25
=====
Comment out the choice of the pyenchant in the example configuration file;
see the heading Example under :ref:`config_file@spell_package` .
This was done because pyenchant is harder to set up on some systems.

.. _2024@mm-dd@08-13:

08-13
=====
The syntax for the literal command was split into the
:ref:`literal_cmd@Syntax@Entire FIle` ,
:ref:`literal_cmd@Syntax@With Separator` , and
:ref:`literal_cmd@Syntax@Without Separator` cases.

.. _2024@mm-dd@08-12:

08-12
=====
Change the :ref:`get_started-name` example to use an empty ``xrst.toml``
configuration file. In addition put xrst.toml in the page for the
:ref:`configuration file<config_file-name>`
(so that it comes up when you search for xrst.toml).

.. _2024@mm-dd@06-25:

06-25
=====
It used to be the case that the following input would cause xrst to crash
in the file auto_indent.py::

   {xrst_begin empty_page}
   {xrst_end   empty_page}

This has been fixed.

.. _2024@mm-dd@04-30:

04-30
=====
Remove the testing wish list item because xrst is now tested on window,
ubuntu, and macos using a github workflow.

.. _2024@mm-dd@04-06:

04-06
=====
#. Add the :ref:`suspend_cmd@boolean` argument to the suspend command
   and allow for suspend and resume commands in a
   :ref:`template_cmd@template_file` .
#. Sphinx errors messages that occurred inside a template expansion
   were reported using the page file and template line.
   This has been fixed and they are now reported with the
   page file, page line, template file, and template line.

.. _2024@mm-dd@04-05:

04-05
=====
Change the default :ref:`literal_cmd@display_file` in the literal command
from the current :ref:`template_cmd@Input File`
to the current :ref:`begin_cmd@Page File` .
This only changes the literal command when it is used in a template file
(template commands became available on 03-28).

.. _2024@mm-dd@03-30:

03-30
=====
#. The automatic special spelling words for a page were extended to include
   page names in ``:ref:`` commands; see :ref:`spell_cmd@page_name` .
   In addition, the words in  *page_name* ,
   that are displayed by this ``:ref:`` command ,
   are checked for double word errors.
#. The keywords in the xrst search utility excluded the words that matched
   :ref:`config_file@not_in_index` .
   This has changed so that the keywords include all the words in a page
   title or heading.
#. Duplicates were removed form the html keyword meta data. In addition,
   commas (instead of spaces) where used to separate these keywords
   (because that seems to be the standard).

.. _2024@mm-dd@03-29:

03-29
=====
#. Add a :ref:`example_expansion_one@Spelling` example in
   the example template expansions.

#. Back out change in definition of
   :ref:`double word <spell_cmd@Double Words>` errors.

.. _2024@mm-dd@03-28:

03-28
=====
#. Add the :ref:`template command<template_cmd-name>` and
   :ref:`template_example-name` .

#. Change the definition of :ref:`double word <spell_cmd@Double Words>`
   errors so that it only refers to the xrst input file, not the
   output that the user sees.

.. _2024@mm-dd@03-19:

03-19
=====
Add the :ref:`run_xrst@external_links` option to the ``xrst`` command line.

.. _2024@mm-dd@03-16:

03-16
=====
Add the template command to the wish list.
This was completed; see 03-28 above.

.. _2024@mm-dd@03-04:

03-04
=====
#. The table of contents page was moved
   from ``xrst_table_of_contents.rst`` to :ref:`auto_file@xrst_contents.rst` .
   In addition, links were added to the page name.
   Old links to the page title had the form::

      :ref:`xrst_table_of_contents-title`

   These links need to be changed to::

      :ref:`xrst_contents-title`

#. The pages with names that begin with ``xrst_`` were modified
   to make the names, titles, and linking text more consistent; see
   :ref:`auto_file@xrst_contents.rst` ,
   :ref:`auto_file@xrst_search.rst` ,
   :ref:`auto_file@xrst_index.rst` ,
   Also see the discussion of linking text for a
   :ref:`heading_links@Labels@Level Zero@page_name` .

.. _2024@mm-dd@03-02:

03-02
=====
There was a bug in the :ref:`xrst_search-name` page (introduced on 2024-02-29).
To be more specific, the search was
loading the page before the one selected. This has been fixed.

.. _2024@mm-dd@03-01:

03-01
=====
The :ref:`user-guide@Install From Source` instructions were improved.

.. _2024@mm-dd@02-29:

02-29
=====
The name of the xrst search page was changed from ``Search``
to :ref:`xrst_search-name` and its link was moved to directly below
the sphinx Search link.
This distinguishes it from the search that comes with sphinx.
The xrst search page was displaying the number of matches displayed,
which is at most 100, instead of the total number of matches.
This has been fixed.
In addition, you can now link to the xrst search using either::

   :ref:`xrst_search-name`
   :ref:`xrst_search-tilte`

.. _2024@mm-dd@02-25:

02-25
=====
A discussion was added for the case where the file list is
:ref:`toc_cmd@File List@Empty` in a toc command.
In addition, the error message was improved for the case
where this list is empty and the page is not a parent page.

.. _2024@mm-dd@02-14:

02-14
=====
If xrst could not translate an error message from its rst line number
to its original input file, a non-zero error flag was set and
just a newline printed to stderr.
This has been fixed and a more meaningful error message is printed
before the program exists.

.. _2024@mm-dd@02-03:

02-03
=====
Adapt pytest/test_rst.py so the tests work on windows and extend
tox.ini so that versions from 3.8 to 3.12 are tested.

.. _2024@mm-dd@01-29:

01-29
=====
Add the :ref:`run_xrst@ignore_spell_commands` option to the
``xrst`` command line.

.. _2024@mm-dd@01-21:

01-21
=====
#. If you used ``docstring_example`` for a :ref:`begin_cmd@page_name`
   and there was a spelling error in that page,
   ``xrst`` would stop at a breakpoint before reporting the spelling error.
   This has been fixed.
#. It was possible for the assert below to fail.
   This has been changed into an error message::

      assert page_name == 'xrst_table_of_contents'

#. The information and suggestions printed below the spelling warnings
   has been improved.

.. _2024@mm-dd@01-04:

01-04
=====
A link to the current release was included; see
:ref:`user-guide@Versions` .

.. _2024@mm-dd@01-01:

01-01
=====

#. The :ref:`get_started-name` example was simplified by using
   the stable release for 2024.

#. A stable version of the documentation was created; see
   :ref:`user-guide@Versions` .

#. Each *file_name* in the latest documentation was moved
   (this is important if you have links to previous web pages):

   .. csv-table::

      Old Location,  ``https://xrst.readthedocs.io/``\ *file_name*
      New Location,  ``https://xrst.readthedocs.io/latest/``\ *file_name*
