sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.53k stars 2.12k forks source link

Sphinx generates mandoc-incompatible man pages with markup inside of tables #11455

Open asomers opened 1 year ago

asomers commented 1 year ago

Describe the bug

mandoc does not support any kind of macros within tables. See https://man.openbsd.org/mandoc.1#ignoring~5 . But Sphinx generates such tables. I suggest that it instead should omit all macros from tables in the man output, preserving them only in the HTML output.

How to Reproduce

index.rst:

=================           =======
This is                     a table
=================           =======
.. envvar:: foo             banana
.. envvar:: blart           mart
=================           =======

conf.py:

project = 'fish-bug'
copyright = '2023, Alan Somers'
author = 'Alan Somers'
extensions = []
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'alabaster'
html_static_path = ['_static']

And here's what mandoc has to say about it:

> mandoc -Tlint -Wunsupp _build/man/fish-bug.1
mandoc: _build/man/fish-bug.1:44:3: UNSUPP: ignoring macro in table: RS 0.0
mandoc: _build/man/fish-bug.1:45:2: UNSUPP: ignoring macro in table: TP
mandoc: _build/man/fish-bug.1:46:2: UNSUPP: ignoring macro in table: B foo
mandoc: _build/man/fish-bug.1:47:3: UNSUPP: ignoring macro in table: RE
mandoc: _build/man/fish-bug.1:47:2: UNSUPP: ignoring macro in table: in 0u
mandoc: _build/man/fish-bug.1:53:3: UNSUPP: ignoring macro in table: RS 0.0
mandoc: _build/man/fish-bug.1:54:2: UNSUPP: ignoring macro in table: TP
mandoc: _build/man/fish-bug.1:55:2: UNSUPP: ignoring macro in table: B blart
mandoc: _build/man/fish-bug.1:56:3: UNSUPP: ignoring macro in table: RE
mandoc: _build/man/fish-bug.1:56:2: UNSUPP: ignoring macro in table: in 0u

Environment Information

Platform:              freebsd14; (FreeBSD-14.0-CURRENT-amd64-64bit-ELF)
Python version:        3.9.16 (main, Mar 11 2023, 01:36:36) 
[Clang 15.0.7 (https://github.com/llvm/llvm-project.git llvmorg-15.0.7-0-g8dfdc)
Python implementation: CPython
Sphinx version:        5.3.0
Docutils version:      0.19
Jinja2 version:        3.1.2

Sphinx extensions

No response

Additional context

No response

grubert commented 1 year ago

but man does support tables

simply removing possibilities for other people seams harsh to me

if you only want mandoc maybe a mandoc-writer-variant would be better or ...