.. -*- coding: utf-8 -*-












.. role:: sref(numref)
.. role:: xref(numref)
.. Copyright (C) 2022, Dominik Appold, <dominikappold at gmx.de>

.. This file is part of Documentation Standard.

.. Permission is granted to copy, distribute and/or modify this document
.. under the terms of the GNU Free Documentation License, Version 1.3
.. or any later version published by the Free Software Foundation;
.. with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
.. A copy of the license is included in the section entitled "GNU
.. Free Documentation License".

.. inline comments (with du_comment_role)
.. role:: rem(comment)
.. role:: html(raw)
   :format: html
.. role:: shx(code)
   :language: sh

.. rst-class:: xnarrow xmedium large xhuge xultra

##################################################
:rem:`|||:sec:|||`\ sda chapter new is Faulty
##################################################
.. >>CODD See `the components of a doctoral dissertation and their order <http://site.uit.no/english/writing-style/bookstructure/>`_
.. >>CODD Dedication
.. >>CODD Epigraph
.. >>CODD Abstract
.. compound::

   The help of :samp:`sda chapter --help` states:

   .. code-block:: text

      COMMAND CHAPTER
        chapter [SUB-COMMAND] [COMMON-OPTIONS] [ARGS]

      COMMON-OPTIONS
        | option              | args | description                                |
        | -p, --preserve-case |      | do not lowercase title for filename suffix |
        | -h, --help          |      | show help                                  |

        chapter new CHAPTER-FILENAME-OR-TOPIC
          * Convert CHAPTER-TOPIC to a canonical name CANONICAL-CHAPTER-TOPIC
            which is suitable as filename README-CANONICAL-CHAPTER-TOPIC.txt

          * Generate README-CANONICAL-CHAPTER-TOPIC.txt, if it does not exist.

   However, this is not how the command actually works.

   With an existing file :file:`README-Check-Chapter-New.txt`, the command

   .. code-block:: sh

      sda chapter new README-Check-Chapter-New.txt

   takes no action. No canonicalization whatsoever  is performed.

   .. \|:here:|

.. >>CODD Introduction
.. >>CODD Chapter

=======================================================
:rem:`|||:sec:|||`\ From Gibberish to Brilliant Clarity
=======================================================

It is obvious, that the phrasing of the help text is less than clear
and should be more precise to produce a meaningful command
description.

-----------------------------------------------------------------
:rem:`||:sec:||`\ BNF Is a Tool That Needs To Be Mastered As Such
-----------------------------------------------------------------

It always helps to construct a BNF syntax declaration or at least have
it in mind to clearly identify the parts of a syntactic entity.

A BNF syntax is constructed top-down. It starts with top-level syntax
elements, which are then further defined until only terminal
definitions or transformations are used.

The production of a BNF syntax is extremely simple:

- define top-level element with terminal and non-terminal elements
- for each undefined element, append a definition placeholder to the
  end of the syntax description
- define the next placeholder element

Starting with the input `CHAPTER-FILENAME-or-TOPIC`, the BNF syntax is
as follows.

.. code-block:: text

   // input

   CHAPTER-FILENAME-or-TOPIC:
       CHAPTER-FILENAME | TOPIC

   CHAPTER-FILENAME:
      PREFIX TOPIC-SUFFIX EXTENSION

   TOPIC:
      "Mixed Case Topic with Spaces"

   PREFIX:
      "README"

   TOPIC-SUFFIX:
      "-" FN-TOPIC | /* empty */

   EXTENSION:
      ".txt"

   FN-TOPIC:
      subst("[^-0-9A-Za-z], "-", TOPIC)

The output of the operation requires a `CANONICAL-CHAPTER-FILENAME`,
which is constructed from some fixed string elements and a transformed
`canonical-topic` derived from a `TOPIC` which is one possible
input. The other possible input is a `CHAPTER-FILENAME`, which
contains a `TOPIC` and must therefore be deconstructed.

.. code-block:: text

   // output

   CANONICAL-CHAPTER-FILENAME:
      PREFIX CANONICAL-TOPIC-SUFFIX EXTENSION

   CANONICAL-TOPIC-SUFFIX:
      "-" FN-CANONICAL-TOPIC | /* empty */

   FN-CANONICAL-TOPIC:
      subst("[^-0-9A-Za-z], "-", canonical-topic)

   canonical-topic:
      lowercase(TOPIC)

It is more appropiate to describe the simpler transformation of a
generic `TOPIC` into a `canonical-topic` and a
`CANONICAL-TOPIC-SUFFIX` before describing the deconstruction of a
`CHAPTER-FILENAME` and then again describing the transformation of the
generic `TOPIC` into a `CANONICAL-TOPIC-SUFFIX`.

The requirement of a `CHAPTER-FILENAME` as input is too strict, it is
better to accept the name of any existing file, construct a proper
chapter filename and rename the input file (`FILE-NAME`).

With option `--preserve-case` the chapter filename output is not
canonical.

All of this should be reflected in the underlying BNF syntax tree:

.. code-block:: text

   // input

   TOPIC-or-FILENAME:
       TOPIC | FILENAME

   TOPIC:
      "Mixed Case Topic with Spaces"

   FILENAME:
      FILEBASE EXTENSION | FILEBASE

   FILEBASE:
      PREFIX TOPIC-SUFFIX | TOPIC

   EXTENSION:
      ".txt"

   PREFIX:
      "README"

   TOPIC-SUFFIX:
      "-" TOPIC | /* empty */

   // output

   CHAPTER-FILENAME:
      PREFIX TOPIC-SUFFIX EXTENSION

   TOPIC-SUFFIX:
      "-" FN-TOPIC | /* empty */

   FN-TOPIC:
      subst([^-0-9A-Za-z], "-", CHAPTER-TOPIC)

   CHAPTER-TOPIC:
       ifelse(--preserve-case, TOPIC, canonical-topic)

   canonical-topic:
      lowercase(TOPIC)

The description should then speak of

- `TOPIC-or-FILENAME`, deconstructed into `TOPIC` and `FILENAME`
- `canonical-topic` (to emphasize the all lowercase requirement of a canonical topic suffix)
- `CANONICAL-CHAPTER-FILENAME`

.. code-block:: text

     chapter new TOPIC-or-FILENAME
       1. If TOPIC-or-FILENAME is the name of an existing file
          - extract TOPIC from FILENAME
       2. If --preserve-case is given,
          - use TOPIC as CHAPTER-TOPIC, otherwise
          - use TOPIC converted to lowercase as CHAPTER-TOPIC.
       3. Construct FN-TOPIC by replacing all non-alpha characters
          in CHAPTER-TOPIC with dashes "-" and squeezing multiple
          dashes into a single dash.
       4. Construct CHAPTER-FILENAME from FN-TOPIC as:
            "README" "-" FN-TOPIC ".txt"
       5. If CHAPTER-FILENAME exists
          - if FILENAME exists
            - if FILENAME is different from CHAPTER-FILENAME
              - warn about existing CHAPTER-FILENAME for FILENAME
            - warn about existing CHAPTER-FILENAME for TOPIC
          - if FILENAME exists
            - if FILENAME is different from CHAPTER-FILENAME
              - rename FILENAME as CHAPTER-FILENAME
            - Create new CHAPTER-FILENAME with title TOPIC.

.. code-block:: sh

   "README-" canonical-chapter-topic ".txt"

.. >>CODD Conclusion
.. >>CODD Appendix A

.. \|:here:|

.. >>CODD Notes
.. ==================================================
.. :rem:`|||:sec:|||`\ Footnotes
.. ==================================================

:html:`<hr>`

.. \[#]

.. \|:info:| put local references here
.. \|:info:| put local definitions here
.. include:: doc_defs.inc
.. include:: abbrev_defs.inc
.. include:: doc_defs_combined.inc
..
  .. \||<-snap->|| doc_standalone
  .. include:: doc/doc_defs_secret.inc
  .. \||<-snap->|| doc_standalone
  .. \||<-snap->|| not_doc_standalone
  .. include:: doc_defs_secret.inc
  .. \||<-snap->|| not_doc_standalone

.. _`Dominik Appold`: dominikappold@gmx.de