在pandoc中的单个文件中对文档和发行说明进行类似文字编程的管理？

Question

在文字编程中，一个有文字的程序以一种文件格式组合代码和散文（文档）：在这个示例中，一个

hello.w

文件包含代码和Latex文本——然后

ctangle hello.w

用于生成一个可编译

hello.c

C 源代码文件，而

cweave hello.w

用于生成文档

hello.tex

。

我已经使用

pandoc

来编写文档，然后通过 Latex 将其导出为 PDF。同时我单独管理一个

RELEASE_NOTES.md

文件，占用自己的时间

现在，我想减少管理所需的时间

RELEASE_NOTES.md

，所以我考虑在单个 Markdown 文件中管理文档和发行说明，类似于在文学编程中在单个文件中管理代码和文档的方式。本质上，我想要的是：

• 单个文件应该可用作主文档的直接来源，如

  pandoc doc_rn_main.md -o doc.pdf

  所示（尽管我也不介意预处理步骤）
• 对于发行说明，应该可以使用

  pandoc

  进行 markdown 到 markdown 转换，可能使用一些特殊的命令行参数，以获得发行说明 markdown 文件，如

  pandoc [arguments] doc_rn_main.md -o RELEASE_NOTES.md

中所示

我不知道

pandoc

中存在此类功能 - 如果我错过了它，我很想知道它。

否则，就

pandoc

的Markdown而言，我想这个问题可以简化为：

• 如何以允许嵌套标签的方式标记或标记一组段落（Markdown 文本）？
• 如何将一小段文本关联到段落标签，作为发行说明的条目？

下面是我想象中最终会出现在主源文档中的伪代码说明，我们称之为

doc_rn_main.md

- 我最近了解了 Org 模式标记（通过 https://github.com/limist/文学编程示例），我认为在这里是合适的，但是我怀疑它是否得到

pandoc

的支持（因此，下面是伪代码）：

# Introduction

MyApp is a program that allows the user to perform some important tasks.

# Starting

Start the MyApp program by double-clicking its icon.

# Device list

Click the "Device list" button in MyApp, to show a list of available devices in the main table.

#+BEGIN_SORT_DEVICE_LIST_FEATURE
#rn-ver:v1.01
#rn-date:2024-04-12
#begin-rn-entry
* Added "Sort" entry in right-click context menu of main device list table
#end-rn-entry

## Device list sorting

Right-click on the main table, and choose "Sort" from the context menu, to sort the device list shown in the table by name, ascending.

#+BEGIN_SORT_DEVICE_LIST_OPTIONS_FEATURE
#rn-ver:v1.02
#begin-rn-entry
* Added "Ascending" and "Descending" submenu entries, for the "Sort" right-click context menu of main device list table
#end-rn-entry

* Hover over the "Sort" menu, to show a submenu with two options: "Ascending" and "Descending"; click any of these to have the device list shown in the main table sorted accordingly
#+END_SORT_DEVICE_LIST_OPTIONS_FEATURE
#+END_SORT_DEVICE_LIST_FEATURE

## Closing the application

Click the X in the upper right corner of the MyApp application window, to close the application.

#+BEGIN_SAVE_CSV_ON_CLOSE_FEATURE
#rn-ver:v1.01
#rn-date:2024-04-12
#begin-rn-entry
* Added automatic saving of main device list table as `MyApp.csv` file upon application close.
#end-rn-entry

Note that when you close the application, the contents of the main device list table will be automatically saved as a CSV file, `MyApp.csv`, in the same directory where the `MyApp` executable is located.

#+END_SAVE_CSV_ON_CLOSE_FEATURE

#+BEGIN_INITIAL_RELEASE
#rn-ver:v1.00
#begin-rn-entry

* Found devices can be listed in the main table shown in the application, by clicking the "Device list" button. 

#end-rn-entry
#+END_INITIAL_RELEASE

#+BEGIN_RELEASE_DATE_TABLE
v1.00 , 2023-12-21
v1.01 , 2024-03-14
v1.02 , 2024-04-12
#+END_RELEASE_DATE_TABLE

然后，为了生成发行说明，我想象运行类似

pandoc [release-note-arguments] doc_rn_main.md -o RELEASE_NOTES.md

的东西，在结果

RELEASE_NOTES.md

中，我会：

# MyApp Release Notes

## v1.02 - Fri, 2024 Apr 12 

* Added "Ascending" and "Descending" submenu entries, for the "Sort" right-click context menu of main device list table

## v1.01 - Thu, 2024 Mar 14 

* Added "Sort" entry in right-click context menu of main device list table
* Added automatic saving of main device list table as `MyApp.csv` file upon application close.

## v1.00 (initial release) - Thu, 2023 Dec 21

* Found devices can be listed in the main table shown in the application, by clicking the "Device list" button. 

然后，为了生成主要文档，我想象运行像

pandoc [main-document-arguments] doc_rn_main.md -o doc.md

这样的东西（然后我会通过

pandoc doc.md -o doc.pdf

将其转换为 PDF），在生成的

doc.md

中，我会：

# Introduction

MyApp is a program that allows the user to perform some important tasks.

# Starting

Start the MyApp program by double-clicking its icon.

# Device list

Click the "Device list" button in MyApp, to show a list of available devices in the main table.

## Device list sorting

Right-click on the main table, and choose "Sort" from the context menu, to sort the device list shown in the table by name, ascending.

* Hover over the "Sort" menu, to show a submenu with two options: "Ascending" and "Descending"; click any of these to have the device list shown in the main table sorted accordingly

## Closing the application

Click the X in the upper right corner of the MyApp application window, to close the application.

Note that when you close the application, the contents of the main device list table will be automatically saved as a CSV file, `MyApp.csv`, in the same directory where the `MyApp` executable is located.

上面的伪代码示例演示了：

• 主源文件的一般流程

  doc_rn_main.md

  保留在输出文档文件

  doc.md

  中，即使有嵌套的发行说明标记 - 但是发行说明文档按发行日期降序排序
• 所有未另行标记的段落均被视为“初始版本”的一部分
• 没有任何文档内容的版本注释标记（例如“初始版本”）也可以用于记录在后续版本中删除的功能（因此它们仍然显示在版本注释中，但不会显示在文档中）
• 发布版本和日期之间的相关性保留为单独的项目，因此如果您复制粘贴版本的错误发布日期，则要做的工作更少

那么，

pandoc

是否有现有的设施可以让我做这样的事情 - 如果没有，那么实施这样的事情的适当方法是什么？

（关于“适当” - 写完上面的例子后，我意识到如果我使用类似 MarkText 的东西来快速预览主源文件

doc_rn_main.md

，我会打印出一大堆

#rn-ver:

的东西，我不希望这样做，因为它会增加认知负担 - 因此通过 Markdown (HTML) 注释实现这些发行说明标记可能会更好，因此它们是不可见的；这也可能有助于摆脱 Markdown 文档；生成步骤

pandoc [main-document-arguments] doc_rn_main.md -o doc.md

，因为我们可以直接从主源文件编译PDF，例如

pandoc doc_rn_main.md -o doc.pdf

）

Answer 1

“pandoc-way”将使用 Lua 过滤器 与“fenced divs”结合使用。

# Device list

Click the "Device list" button in MyApp, to show a list of
available devices in the main table.

::: {.release-note version="v1.01" date="2024-04-12}
Added "Sort" entry in right-click context menu of main device list table
:::

需要两个过滤器，一个用于生成主文档，另一个用于发布说明。主文档的过滤器很简单，因为它只会删除发行说明：

function Div (div)
  if div.classes:includes 'release-note' then
    return {}  -- delete div
  end
end

与

pandoc --lua-filter=remove-release-notes.lua ...

一起使用。

编写一个过滤器来收集和排序发行说明会更复杂一些。如果您在编写该过滤器时遇到问题，并且有具体问题，那么您可以在此处或在 pandoc 讨论板上提问。