Hi, Thanks for your interest to improve DR.
I don't fully understand your message but let's start discussion. On Wed, 2026-09-30 at 07:32 -0700, Osman Vielma wrote: > 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. I understand that the current TEXT format output is not optimal for table 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) > 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. If I understand correctly, you are suggesting a text output format following markdown-derivative is easier to read from you? > Could the build provide Markdown output alongside HTML and the other formats? 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. > 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 > 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.) > 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. Using XML source as the start is the right approach. 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 > 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. Obviously, as I mentioned above, I have no access to what you created. > 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. It is a reasonable option to replace current text output with any reasonable alternate such as markdown-compatible text rendering. > I've attached a screenshot of the converted preface in Obsidian. A sample > chapter and the README are also available if useful. 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
