Hello,

I'm studying the English Debian Reference 2.100. For me, the HTML and PDF
versions, and the plain-text version with hardcoded line breaks, are simply
impossible to read comfortably. Markdown in Obsidian makes a huge
difference: I can finally read the book in a format that works for me and
keep it alongside my study notes.

Could the build provide Markdown output alongside HTML and the other
formats?

As a proof of concept, I converted the complete English book from its
DocBook XML source to GitHub Flavored Markdown: the preface, 12 chapters
and appendix, plus a README. The source was:

https://salsa.debian.org/debian/debian-reference
Tag: debian/2.100
Commit: 10151371e400a1dba15a34c67cf758cf081afb85

The conversion used Pandoc after resolving the source entities and applying
the repository's table and URL transforms. It did not use the packaged HTML
as input. All 303 code blocks and 170 tables were checked against the XML,
and the 235 internal reference destinations were checked. Relative links
work when the Markdown files are kept together.

This is a proof of concept, not a ready-to-merge build patch or a
line-by-line editorial review. Some handling was needed for admonitions,
table captions and cross-references. Wide tables also depend on the
reader's Markdown viewer.

Would an optional Markdown build target, using Pandoc or another suitable
converter, be worth adding? The aim would be to generate the files from the
same source, without maintaining a separate copy of the book.

I've attached a screenshot of the converted preface in Obsidian. A sample
chapter and the README are also available if useful.

Thank you for the book.

Osmancito

Hi,

Thanks for your interest to improve DR.

I don't fully understand your message but let's start discussion.
rendering.  It's basically text dump of 1-page HTML output using "w3m".  This is
more or less meant for a resource file to "grep" some topic.  It was a quick
hack.

HTML and PDF, I see no issue.  For HTML under the modern high resolution display
on small lapptop PC, some texts may be displayed too small for old man like me.
I simply set "zoom" setting of my browser to 150% or so.  There is no "hardcoded
line breaks" problem in HTML.

Before discussing technical details of "SOLUTION", I need to understand your
"CONCERN" and your "SITUATION".

Q1: Are you reading DR with your eyes with normal vision?  If you have vision
challenges, let me know your challenges which HTML+ZOOM doesn't solve. (If you
are using braille terminal, I understand the current TXT output is non-optimal.)

Q2: Let me assume, you don't wish to use any typical HTML browsers for some
reason and want to read DR using some text viewer or text editor.  If so, do you
accept very long line for table row.  (The current text output width is fixed
and a row of table data is multi-folded lines in boxed area)

If I understand correctly, you are suggesting a text output format following
markdown-derivative is easier to read from you?

TBH, I don't want to keep adding anther format.  Output should be minimal set
with reasonable demand.  (FYI: I dropped epub.)  If there is a better text
rendering, we should switch to that new text rendering.  After all, markdown
format is a text file.

I don't understand this.  Did you push directly to
https://salsa.debian.org/debian/debian-reference while overwriting the existing
valid tag.  I don't think you did so.  (Please don't do it.)

If you cloned repo, please let me know your cloned repo site URL so I can fetch
it.  Please use tag names which don't collide with existing one.  (I suggest you
to create a new branch on your cloned repo.)

TBH, I want to keep build script to be as simple as possible.  If possible, I
want to avoid using pandoc.  Simple XSLT converter from XML to text in one
approach I seriously thought about.

With this, we can fine tune text output.  (E.g., while dropping HTML references
in table for readability.)

See how things work with xslt:
https://lennybacon.com/posts/xmltomarkdownwithxslt/
https://stackoverflow.com/questions/8800269/xslt-to-convert-xml-to-text
https://gist.github.com/guobin2312/6e6e92a734e04ae80c481cc5f401d5cd
https://markdownconverters.com/best/xml-converter-2026

Obviously, as I mentioned above, I have no access to what you created.

It is a reasonable option to replace current text output with any reasonable
alternate such as markdown-compatible text rendering.

I don't know nor use obsidian.  Are you talking https://obsidian.md/

This example doesn't have table in it .  It looks very similar to ZOOMed HTML
output.

Anyway, dropping w3m dependency and directly converting from
from `$(MANUAL).%.xml` to rendered markdown output using completely revised
xsl/style-txt.xsl without piping through w3m is the way to go.
(See Makefile around txt target.)

Osamu

Hi Osamu,

Thank you for taking the time to discuss this. My first message did not
explain the use case clearly. I am not proposing to replace HTML or PDF.

The motivation is your second scenario: I want to download the book as a
plain-text file with basic formatting, read it on my own devices,
especially my phone, and keep it alongside my study notes. I use Markor, an
open-source Markdown reader/editor on mobile; Obsidian (yes,
https://obsidian.md/); and MarkLens, a Markdown extension for Firefox.
Obsidian was one example, not the reason to choose the format.

The benefit for me is having headings, lists, quotations, code and tables
in a file that I can read and edit directly. Browser zoom helps with text
size, but it does not give me that same reading and editing workflow. My
concern is this workflow rather than a request for a special accessibility
format. I should also have made clear that the hardcoded line breaks
referred to TXT, not HTML.

Long table rows are fine with me. I have no problem with horizontal
scrolling when a table needs it; I have found the rendered Markdown tables
comfortable to read in MarkLens. I understand that the appearance depends
on the viewer.

To clarify the source reference: debian/2.100 and the commit hash
identified the source used for the conversion. Nothing was pushed to the
official repository and no tag was overwritten. I have attached chapter 3,
"The system initialization", from that proof of concept, plus a screenshot
of a local GFM preview showing a table and a code block. The screenshot is
not from Obsidian or Markor. Some links in the chapter point to other
chapters and need the rest of the files beside it.

I understand your wish to avoid another output format and an extra build
dependency. Markdown-compatible text as an improvement to the current TXT
output sounds worth exploring. Pandoc was used for this proof of concept;
it was not intended as a required implementation choice. Your suggestion of
going directly from XML through XSLT makes sense as a direction to
investigate.

This is still a sample of the desired output, not a ready-to-merge build
patch. The attached files show the use case and the table rendering.

Thank you for the book.

Osmancito

Hi,


Thanks for quick reply.
This looks reasonable.
addressing all the corner cases.


FYI: See my draft MR
https://salsa.debian.org/debian/debian-reference/-/merge_requests/31

Can you share your code.  So I can leverage it to make it ready for merge.

Osamu

Hi Osamu,

Attached is the code from the Pandoc proof of concept, with the Lua filter
and instructions to run it against debian/2.100. I made the source and
output paths configurable and checked that it reproduces the chapter 3
sample I sent you byte for byte with Pandoc 2.9.2.1.

It starts from the merged DocBook XML, applies the repository's table and
URL transforms, resolves the entities and cross-references, and then
converts to GFM. The README describes the extra handling for tables and
admonitions, and the limitations. This is still a proof of concept, not a
ready-to-merge build patch.

Using Pandoc in place of w3m sounds worth exploring. Thank you for sharing
your draft MR; I would welcome adapting this code to that approach.

Osmancito

Hi Osamu,

Thank you, I am glad the PoC was useful. And thank you for pushing the "md"
branch forward.

On your questions:

* Chapter-by-chapter output: yes, I think it is better. It matches the
source structure (one XML file per chapter), mirrors the chunked HTML
output, and is much easier to read and edit, especially on a phone. For
what it is worth, the PoC I sent already works this way: convert.py writes
14 Markdown files (preface, chapters 1-12, appendix) with relative links
between chapters.

* Chapter-by-chapter with XSLT and xsltproc: yes, this should be possible.
XSLT 1.0 has no standard multi-file output, but xsltproc (libxslt)
implements the EXSLT exsl:document extension element, which writes
subsidiary result documents from a single transformation. That is the same
mechanism the DocBook XSL chunking stylesheets (chunk.xsl / chunker.xsl)
use to write one HTML file per section, so a chunked Markdown XSLT along
those lines should work. If it helps, I can try a small chunked variant of
your md XSLT as a test and report back.

* Removing the useless space: the space comes from whitespace-only text
nodes in the source, as in <ulink ...> <literal>mc</literal> </ulink>. Two
XSLT-side options:
- <xsl:strip-space elements="ulink"/> drops whitespace-only text node
children of ulink. It only removes nodes that are entirely whitespace, so
real spacing in mixed text like "see <literal>x</literal>" survives.
- normalize-space() around the link text when the ulink template builds the
Markdown link also cleans it.

In the PoC this never came up because the Python preprocessing runs the
repository's table and URL transforms on the merged XML first and
normalizes the markup before Pandoc sees it.

Osmancito

Osamu, please get some rest. I am glad to be working alongside you.

Osmancito

Hi,

Quite impressive.

I understand your code includes some operations which should be moved to
Makefile but well written to show how you did.  TBH, I never knew how to use lua
filter with pandoc.

I tried to use pandoc as shown in my MR draft:

https://salsa.debian.org/debian/debian-reference/-/merge_requests/31


Here, this code on "md" branch creates a huge single markdown file in build/
directory  upon running:

$ make txt LANGPO=ja.

As I checked how markdown and gfm version looks under my text viewer (neovim
with syntax highlight and hiding.)  GFM looks better than pandoc's MARKDOWN.

Use of xsltproc leaves space in XML like `<ulink ...> <literal>` causing
generated gfm to have `[ `mc` ](...)`.  Your python-lxml generate XML file with
`<ulink ...><literal>` (no space) resulting `[`mc`](...)`.  (nicer)


Before going further, can you tell me a few things.

* Do you think chaper-by-chaper file output is better? (I think so too.)
* Can you implement similar chaper-by-chaper file output using xslt and
  xsltproc   (I suppose html generating xslt does this, so we should be 
  able to do it.)
* Do you know how to remove useless space?

Osamu