Recent changes to 97: --disable-tab-expansion flag

#97 --disable-tab-expansion flag

Günter Milde — Tue, 05 Mar 2024 16:40:53 -0000

Two minor points:

You can add a class value to a literal block preceding it with a "class" directive ("rst-class" with Sphinx):

.. class:: testme

::

   a literal block

TABs are converted to spaces in literal blocks, too :(

#97 --disable-tab-expansion flag

Günter Milde — Tue, 12 Dec 2023 16:14:18 -0000

The negative value for the TAB expansion width is only supported for literal inclusions, not for the main document or included rST files.

#97 --disable-tab-expansion flag

Günter Milde — Thu, 09 Nov 2023 17:04:17 -0000

A patch-set was posted to the "docutils-develop" mail list on 2023-10-29. See the thread in the archive.

#97 --disable-tab-expansion flag

toastal — Sun, 16 Jul 2023 10:27:37 -0000

Understanding my ask a bit more now:

I want a code block options for :tab-width: -1, tho preferably I want this on a global flag because I do not want docutils to convert my tabs to spaces so my code is a) easier to copy from a post and b) so the reader may adjust the tab widths while reading.

Tab conversion was unexpected as reStructuredText seemed to have no issues allowing me to use tabs as indentation for block as well as indentation inside code-blocks. Documentation was also confusing where some things (e.g. directives, CLI flags) had tab-width options that allowed values <1 whereas others did not.

I considered trying to use a literal block, ::, as a workaround, but without the ability to add classes there would be no way to discern a “code block” literal from a literal literal. My best idea for a workaround for now is, for HTML at least, do a post-processing phase that finds all code blocks and runs their contents through GNU unexpand. This is obviously not ideal. Using the code-block will still keep the document readable & allows Tree-sitter to highlight the children, so this hack will have to do.

#97 --disable-tab-expansion flag

toastal — Sun, 16 Jul 2023 09:41:13 -0000

[restructuredtext parser]
tab-width = -1

Did not work in a docutils.conf file either.

#97 --disable-tab-expansion flag

toastal — Sun, 16 Jul 2023 09:33:02 -0000

docutils: error: Error in option "--tab-width":
ValueError: negative value; must be positive or zero

No luck actually trying.

#97 --disable-tab-expansion flag

toastal — Sun, 16 Jul 2023 09:31:59 -0000

A negative value prevents expansion of hard tabs.

Found somewhere else in the docs. Not it the --help text. Missing from https://docutils.sourceforge.io/docs/user/config.html#tab-width

--disable-tab-expansion flag

toastal — Sun, 16 Jul 2023 09:21:39 -0000

Spaces are recommended for indentation, but tabs may also be used. Tabs will be converted to spaces. Tab stops are at every 8th column (processing systems may make this value configurable).

Why tho? By converting tabs to spaces, we lose the accessibility aspect that tabs provide by letting the reader decide what’s comfortable to them as tab-width should be configurable on the reader’s side, not the writer’s. Some programming languages, like Go, tabs are overwhelmingly preferred & sometimes even required. Copying some code would not work.

I would like to see a --disable-tab-expansion flag that lets the author choose how they want their output to be output.