Honour predefined registers when initialising `ms`

[Alhadis]

This pull-request updates the ms package to honour predefined values for the following registers:

\n(HM - Header margin
\n(FM - Footer margin
\n(PS - Point size
\n(VS - Vertical spacing
\n(PO - Page offset
\n(LL - Line length

/cc @rnkn You're more familiar with the ms macro set than I am: could you test these changes locally and confirm they're working as intended? They should behave the same as their Groff counterparts.

Resolves: n-t-roff/heirloom-doctools#111

[n-t-roff]

@Alhadis thank you. Are these register names identical to the registers in groff's ms which can be set per -p option? I wait for @rnkn 's response and maybe someone else would like to test or review. After that it gets applied. (Unfortunately there does not seem to be any ms documentation in the heriloom doctools package, which could be updated now.)

[Alhadis]

Are these register names identical to the registers in groff's ms which can be set per -p option?

Yes. I intentionally used those registers which groff_ms(7) documents as user-configurable (listed under "Document control settings").

[rnkn]

Given there doesn't appear to be any documentation on Heirloom ms I think it's probably only worthwhile merging this if all the registers listed in groff_ms(7) under Document control registers are available.

[Alhadis]

I think it's probably only worthwhile merging this if all the registers listed in groff_ms(7) under Document control registers are available.

@rnkn Why? These don't have to be documented to be useful; #111 is testimony to that.

[rnkn]

@rnkn Why? These don't have to be documented to be useful; #111 is testimony to that.

Quite the opposite. I reported #111 after hours of frustration, thinking I must have the syntax wrong, or there was something in my source file overriding things. Given there was no documentation, all I had to go on groff_ms(7). (Had troff(1) had some hint that ms registers were not implemented would have been more useful.)

Implementing a subset of ms registers, and not documenting which or why, would take the above situation and make it much worse; then instead of the -r flag having consistently no effect, it would have an inconsistent effect, and so be more inscrutable to the person trying to use it.

[Alhadis]

The classical macro packages are littered with undocumented, arcane features like these. I'd argue this is a problem of inadequate documentation, and not one of missing features. Moreover, implementing every other request as documented in groff_ms(7) still doesn't solve the documentation issue.

then instead of the -r flag having consistently no effect, it would have an inconsistent effect

The -r flag works perfectly fine. This was simply a missing implementation detail that Groff's ms had that Heirloom's didn't. Basically this:

Groff's ms package	Heirloom's ms package
~~~bash #!/usr/bin/env bash if [[ "$SOME_ENVIRONMENT_VARIABLE" == "" ]]; then export SOME_ENVIRONMENT_VARIABLE='6' fi ~~~	~~~bash #!/usr/bin/env bash export SOME_ENVIRONMENT_VARIABLE='6' ~~~

[n-t-roff]

How about copying a manpage from some other AT&T roff derivative, e.g. ms.5 from DWB and update it to the heirloom doctools functionality? Licence issues would need to be checked of course.

[Alhadis]

@n-t-roff IMHO, that elevates the risk of copying inaccurate documentation, as I'm sure there've been changes between DWB's version of ms.5 and where ours currently stands today.

To be frank, I deem this to be a completely unrelated issue. This was intended as a minor enhancement, and I've neither the time nor the inclination to port every damned register that groff_ms(7) supports that's been omitted in this PR.

[n-t-roff]

It was not my intention to be 100% groff compatible, but rather to use a ms documentation which describes the AT&T ms implementation and adds the changes made.

But for me it is OK too to just commit your pull request without additional documentation (although I partly agree to @rnkn 's concerns). I'll wait for another 24 h for further objections, then the patch gets committed.

[Alhadis]

which describes the AT&T ms implementation and adds the changes made.

Have there been that many changes, though? I'm really not at all that familiar with the ms package, and even less so on its revision history in the Heirloom project…

If it's really just a matter of copying, pasting, and adding a few segments, then hell, I'm happy to do that.