more explanation

aastex62/demo.md

@@ -81,6 +81,8 @@ This set of templates specifically utilizes the `pandoc` Markdown flavor^[<https
 It currently supports 25 input formats and 47 output formats (including variations of standards).
 Additional formats can be supported by providing user-defined writers, written in the lua language.
 `pandoc` is written in the Haskell programming language and supports extensions written as filters.
+`pandoc` works by taking one or more input files and applying document templates to generate outputs in a different format.
+Default templates are supplied with `pandoc`, but here I will demonstrate the use of a custom template to create \aastex\-compatible output.
 During the document conversion `pandoc` can use additional metadata specific in a YAML ("YAML Ain't Markup Language") header.
 This header can either be prepended to the Markdown text or incorporated from a separate file.
 
@@ -88,7 +90,7 @@ In order to convert Markdown source into a \TeX\ file which is compatible with j
 Note that the author can write \TeX\ directly into the Markdown file and `pandoc` will happily pass it through to the finished product.
 However, this may compromise alternate (non-\TeX) output formats.
 For example, the \aastex\ `deluxetable` environment can be used, but it will not be rendered as a table in non-\TeX\ formats and will instead be displayed as the raw \TeX\ source (or worse).
-Pandoc filters^[<https://pandoc.org/filters.html>] can be crafted to convert simple `pandoc` tables into `deluxetable`s on the fly, if desired.
+`pandoc` filters^[<https://pandoc.org/filters.html>] can be crafted to convert simple `pandoc` tables into `deluxetable`s on the fly, if desired.
 
 ## Paper Organization
 
@@ -100,18 +102,22 @@ Throughout I assume the reader is familiar with Markdown and do not discuss Mark
 Instead I discuss the general behavior of the template file and actions which are necessary for generating \aastex-compatible output.
 
 The Markdown file, `pandoc` invocation, and associated filters used to create the \TeX\ for this document are available at: <https://github.com/privong/papers-in-markdown>.
+The text of this document is in the `aastex62/demo.md` file.
 This approach can be extended to the templates of other journals by modifying the YAML header in the Markdown file and the \TeX\ template file.
 Bare-bones examples for MNRAS and A\&A are provided in the same github repository.
 
 # Manuscript Preparation in Markdown {#sec:prep}
 
+
+
 ## Manuscript Metadata and Styles {#sec:style}
 
 The Markdown file can be prefixed with a header in the YAML format.
 Article data such as the title, relevant dates, author list, keywords, etc. is specified here.
 This header information is extracted via a \TeX\ template file and passed through to the desired output file.
 The `pandoc` template also derives the \aastex\ style information from this YAML header, via the `aastexopts` entry.
-The YAML header given below is that used for the preparation of this document:
+Document authors can include additional \TeX\ packages by specifying them in the header as `texpackages` entries, as shown below.
+This YAML header is similar to that used in preparing this document:
 
 ```{#yamlheader .numberLines caption="YAML Header Example"}
 ---
@@ -149,11 +155,12 @@ abstract: |
 ---
 ```
 
-Unwanted entries can be commented out with a `#` or safely deleted (here they have been commented so they appear for reference purposes).
-If a different style (e.g., `twocolumn`) is desired, this can be changed in `aastexopts`.
+Unwanted header entries can be commented out with a `#` or safely deleted (here they have been commented so they appear for reference purposes).
+If a different style (e.g., `twocolumn`) is desired, this can be changed in `aastexopts`, and these options will be passed through to the \TeX\.
 YAML header entries and corresponding \TeX\ template code have been created to correspond to most (if not all) of the \aastex\ metadata options.
 
-As a short example, this code in the `aastex62_template.tex` file processes any Received/Revised/Accepted YAML entries and inserts them into the resulting \LaTeX\ output:
+Entries in this YAML header are made available to the `pandoc` processing steps and conditional statements in the applied document template(s).
+As a short example, this code in the `aastex62/aastex62_template.tex` file processes the r`eceived`/`revised`/`accepted` YAML entries and inserts them into the resulting \LaTeX\ output:
 
 ```
 $if(received)$
@@ -185,10 +192,7 @@ the colored points. From @Privon2017b.](images/dm1647.png){#fig:dm1647 width=3in
 
 ## Tables {#sec:tables}
 
-This tool will pass \LaTeX\ tables through `pandoc` to the chosen \LaTeX\ parser.
-Thus, any tables which are part of \aastex\ (e.g., `deluxetable`) will work for producing PDFs.
-However, such \TeX\ tables will not be appropriately rendered in other output formats with which `pandoc` is compatible.
-
+Markdown has its own table formats, which `pandoc` will convert into \TeX\.
 [Table @tbl:storms] is an example of a `pandoc` Markdown "simple table".
 
 Date        Day              Number of storms
@@ -219,6 +223,11 @@ Date        Day              Number of storms
 Table: Number of imaginary thunderstorms in Gainesville, FL during the 21st week of 2018. {#tbl:storms}
 ```
 
+`pandco` will pass \LaTeX\ tables through the chosen \LaTeX\ parser.
+Thus, tables listings in the Markdown file (e.g., \aastex\ `deluxetable`) will be appropriately rendered when producing PDFs.
+However, such \TeX\ tables will not be converted from \TeX\ to other output formats when embedded in a Markdown file.
+So the benefits of directly including \TeX\ tables in the Markdown file must be weighted against the desred flexibility in output formats.
+
 ## Citations {#sec:citations}
 
 Citations can be incorporated using the `pandoc-citeproc` filter.
@@ -240,12 +249,16 @@ For example, entering: `$$e^{i\pi} + 1 = 0$$ {#eq:euler}` results in this output
 $$e^{i\pi} + 1 = 0$$ {#eq:euler}
 
 This method of specifying math and equations can be coupled with `pandoc`'s support for a variety of methods to render math in many other output formats including HTML^[<https://pandoc.org/MANUAL.html#math-rendering-in-html>].
-The bracketed expression at the end creates an in-text reference, similar to the `\\label{}` command in \LaTeX.
+The bracketed expression at the end creates an in-text reference, similar to the `\label{}` command in \LaTeX.
 With such a label, [Equation @eq:euler] can also subsequently be referenced in the text by writing `[Equation @eq:euler]`.
 
 # Notes on Preparation for Submission {#sec:notes}
 
-## Available Templates
+With a Markdown file now containing the text of the manuscript, some short additional steps must be taken to transform that Markdown source into a format suitable for submission to a journal.
+This includes applying an appropriate \TeX\ template ([Section @sec:templates]), scripted modification of documents on the fly ([Section @sec:filters]), and some minor clean-up of the resulting \TeX\ source ([Section @sec:texclean]).
+The latter two steps are essentially optional, though document filtering may be helpful to facilitate dissemination of the manuscript in additional formats beyond the journal's PDF format.
+
+## Available Templates {#sec:templates}
 
 I have created templates and demonstration files for the AAS Journals, Monthly Notices of the Royal Astronomical Society, and Astronomy & Astrophysics.
 The AAS Journals example (which you are reading now) is the most detailed, while the others are bare-bones and intended to constitute a minimal starting point.
@@ -256,12 +269,12 @@ For example collaboration information can be provided to AAS Journals, but not t
 Hence it makes some sense to keep the Markdown templates separate for these journals.
 However, if a manuscript is prepared using the Markdown template for A&A but the authors later decide to submit to MNRAS, the only major changes needed will be to the YAML header in the Markdown file.
 
-## Document Filters
+## Document Filters {#sec:filters}
 
 `pandoc` supports user-written filters.
 These filters enable customized processing of documents during conversion.
-Commonly used languages for this include Haskell, lua, and python^[Using either the `panflute` or `pandocfilters` modules.].
-Note that a lua parser is included with `pandoc` versions 2.0 and newer, and the use of lua filters is faster than other options.
+One example of desirable filter processing is to convert tables formatted in Markdown into \aastex\ `delxuetables`.
+Use of such a filter would make it easier to convert the Markdown source to other formats (e.g., HTML, ePUB) without needing to rewrite a \TeX\ table.
 
 Simple filters are straightforward to construct and I demonstrate one here.
 With output formats besides \aastex\ in mind, the acknowledgments portion of the document has been delineated in the Markdown file as a macro: `{{acknowledgments}}`.
@@ -285,38 +298,40 @@ return {
 }
 ```
 
-A variant of this filter is included as `aastex62/filters/acknowledgments.lua` in the template distribution and similar filters are included for the MNRAS and A&A templates.
-It can is included by adding the `--lua-filter=` command-line argument to `pandoc`.
-This filer be easily extended to generate acknowledgement sections for other output formats, including HTML.
-
-Generally, creation of filters would be more broadly useful in automating the conversion of Markdown files into journal-compatible \TeX.
-An opportunity for this is to write a filter that takes the Markdown "simple table" format and converts it into an \aastex\ `deluxetable`.
+This filter can be expanded to handle other output formats by adding additional `elseif` clauses for other `FORMAT` types.
+A variant of this filter with an additional handling for HTML documents is included as `aastex62/filters/acknowledgments.lua` in the template distribution.
+Similar filters are included for the MNRAS and A&A templates, whose style files handle acknowledgements in a different way.
+These filters are included in the processing chain by adding the `--lua-filter=` command-line argument to `pandoc`.
+Commonly used languages for writing `pandoc` filters include Haskell, lua, and python^[Using either the `panflute` or `pandocfilters` modules.].
+Note that a lua parser is included with `pandoc` versions 2.0 and newer, and the use of lua filters is faster than other options.
 
 ## Internal References
 
 Naively `pandoc` does not support internal reference to figures or equations and does not support numbered section references.
 However the `pandoc-crossref` filter adds support for this (and has been used in the preparation of this document).
 `pandoc-crossref` uses the same syntax as `pandoc-citeproc`, so adds little cognitive overhead in inter-document referencing.
-However in order avoid `pandoc-citeproc` processing internal references, `pandoc-crossref` must be invoked first.
+However to avoid `pandoc-citeproc` incorrectly processing internal references, `pandoc-crossref` must be invoked first.
 
-## \TeX\ Clean up
+## \TeX\ Clean up {#sec:texclean}
 
 A small amount of clean \TeX\ source cleanup may be necessary after running the Markdown through `pandoc`.
 The YAML header elements are incorporated into the manuscript using `for` loops, which may leave trailing punctuation in lists (e.g., a trailing em dash following the list of keywords).
-These will show up in the final output source unless they are removed at the intermediate stage.
+These will show up in the final output source unless they are removed at the intermediate stage between \TeX\ generation and PDF compilation.
 
 # Summary
 
 I have provided a brief demonstration for a method of writing research articles in Markdown and converting them to an \aastex-compatible format for submission to AAS Journals.
 The accompanying template and source code release also includes templates for MNRAS and A&A.
 The advantage of this approach is improved readability of the source files and added flexibility in output formats.
-The latter makes it easier for authors to share HTML and/or EPUB versions of manuscripts, potentially improving uptake.
+The latter makes it easier for authors to share HTML and/or EPUB versions of manuscripts, potentially improving dissemination of results.
 
-I emphasize that this pandoc approach does not supplant the journal-provided \LaTeX\ templates, but instead complements it by providing easier access to additional output formats.
+I emphasize that this `pandoc` approach does not supplant the journal-provided \LaTeX\ templates, but instead complements it by providing easier access to additional output formats.
 This approach is also flexible and does not lock the author into a single format.
-If at any point an author feels unable to progress in Markdown alone, \TeX\ can be embedded directly into the Markdown or `pandoc` can be used to convert the Markdown to a \TeX\ file and the author can resume writing as if they had been writing in \TeX\ all along.
+If at any point an author feels unable to progress in Markdown alone, \TeX\ can be embedded directly into the Markdown (though this potentially compromises the flexibility in well-formatted outputs besides \TeX\ or PDF).
+Alternately, `pandoc` can be used to convert the Markdown to a \TeX\ file and the author can move to editing that \TeX\ file as if they had been writing in \TeX\ all along.
 
 I have made the templates and demonstration text publicly available for use and modification by the community: <https://github.com/privong/papers-in-markdown>.
+The code is licensed under the GPLv3 (or later) and the the documentation is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
 Comments, bug reports, and enhancements are welcome.
 
 {{acknowledgments}}