search

dbry / WavPack

WavPack encode/decode library, command-line programs, and several plugins
BSD 3-Clause "New" or "Revised" License
362 stars 66 forks source link

drop xslt leftovers #155

Closed janstary closed 1 year ago

janstary commented 1 year ago

We don't need XSLT any more. Sorry, I forgot this one when cleaning up after the manpage rewrite.

dbry commented 1 year ago

No problem. I'm editing the individual pages and I'll just throw this into my commit.

BTW, I noticed a couple things. One is I thought I'd like to replace "BSD General Commands Manual" with "WavPack Executable Programs" (like it is in the originals) but couldn't figure out how. So I Googled and the first hit was you complaining about this 9 years ago!! Further Goolging revealed that I wasn't going to be able to change that. Okay.

Next I tried replacing "The options are as follows:" with ".Sh OPTIONS" and that looks better to me (and matches the original) but I'm thinking you must have done that on purpose, even though most random manpages I checked use another section for options. Does doing that trigger some warning somewhere?

janstary commented 1 year ago

The OPTIONS replacement is deliberate, see http://man.openbsd.org/mdoc and the commit messages in e.g. https://github.com/dbry/WavPack/commit/1487f0c4a2df8b829d37c0486e4232d12ba393b0

In particular, mandoc -Tlint complains about nonstandard Sh sections. In standard manpages, such as ls(1), cat(1) and other section 1 utilities, the options are naturaly part of the DESCRIPTION. It's your call of course.

Generally, I tried to minimize any intervention to the actual content, sticking to just the markup rewrite; this was to silence a warning. Tweaking the actual content is the next step I have in mind, but forst I will wait for your edits/comments.

(I am glad to hear that some developers still care!)

janstary commented 1 year ago

The manpages don't introduce "BSD General Commands Manual" anywhere. It's the formatter, when formatting the manpage for viewing, most probably filling in a string for section 1. What system and formatter is this? Is it groff on a Linux?

For example, on this macOS I am sitting at now, the displayed header says WVTAG(1) General Commands Manual WVTAG(1) and the footer is Darwin 22.2.0 January 3, 2023 Darwin 22.2.0 just like for e.g. ls(1), and I believe that's good thing: uniformity of manpages. In particular, I see no point in having a specific "WavPack Executable Programs" header.

That's mandoc on macOS; other formatters (groff, heirloom) on other systems will differ, displaying other strings and other parts of uname(3). I will look and see on other systems once I am at the machines. But generaly I believe we should let the system formatter display whatever it does.

janstary commented 1 year ago

See e.g. https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common where the various strings such as "General Commands Manual" are introduced

dbry commented 1 year ago

The manpages don't introduce "BSD General Commands Manual" anywhere. It's the formatter, when formatting the manpage for viewing, most probably filling in a string for section 1. What system and formatter is this? Is it groff on a Linux?

For example, on this macOS I am sitting at now, the displayed header says WVTAG(1) General Commands Manual WVTAG(1) and the footer is Darwin 22.2.0 January 3, 2023 Darwin 22.2.0 just like for e.g. ls(1), and I believe that's good thing: uniformity of manpages. In particular, I see no point in having a specific "WavPack Executable Programs" header.

That's mandoc on macOS; other formatters (groff, heirloom) on other systems will differ, displaying other strings and other parts of uname(3). I will look and see on other systems once I am at the machines. But generaly I believe we should let the system formatter display whatever it does.

I agree that letting the system formatter do whatever it does is the right way to go, especially since I don't really see an alternative. I'm on Pop!_OS and it is showing BSD which is obviously not even close, but that's not our fault. Of course, I haven't actually installed the manpages (I'm doing man man/wavpack.1). Maybe it will make a difference.

janstary commented 1 year ago

The xslt commit is included in https://github.com/dbry/WavPack/pull/156 , closing here