Re: Viewing PDFs. (Was: Happy new Sun)

[G. Branden Robinson]

At 2022-12-27T23:43:00+0100, Steffen Nurpmeso wrote:
> G. Branden Robinson wrote in
>  <20221227095728.c7oo2iolmg6hl4nw@illithid>:
>  |At 2022-12-24T23:39:07+0000, Deri wrote:
>  |>> "o" for the former.
>  |>> 'That said, https://ftp.sdaoden.eu/code-mailx-1.pdf (beware:
>  |>> 1MB!), realized with newest minor of mdocmx on groff
>  |>> 1.23.0.rc1.2915-c6d7,
>  |
>  |That is 730 commits behind master, FWIW.
> 
> Well sorry, i cannot rebase mdocmx whenever you rename a mdoc
> variable and do other notational beautification, like changing
> doc-arg-limit to doc-arg-count, which happens quite frequently,
> especially since the mdocmx contrib issue has been opened, i would
> think.  So i have to rename 259 occurrances of this to stay in
> sync just for you to have fun.

Have you heard of encapsulation?  Data hiding?  Interface boundaries?

_Don't use package internals unless you're prepared to deal with the
consequences._

> Or that .Sx quotes the arguments, which breaks mdocmx, because
> until now doc-enclose-string was not necessary for all the
> possible references .Sh, .Ss, (.Sx), .Ar, .Cd, .Cm, .Dv, .Er, .Ev,
> .Fl, .Fn, .Fo, .Ic, .In, .Pa, .Va and .Vt.

doc-enclose-string is an internal implementation detail, documented
nowhere, and, in case I need point it out, not present in BSD mdoc(7).

> Enclosing section references in quotes has never been done in UNIX
> manuals, may it be man(7) or mdoc(7).

"Never" is a strong claim.  But I don't doubt it's at least somewhat
innovative in the domain of manual pages, albeit not a novelty of any
sort in general English usage.  This is a basic convention that is
taught in primary school.  Man pages have probably gotten away without
it for so long because of the convention of shouting the section titles,
and neglecting or inconsistently using subsection headings in the first
place.

Consider:

--snip--
        When to Use Quotation Marks

        Quotation marks enclose the titles of:
         Short works

         Sections of long works including chapters, articles, songs,
          short stories, essays, poems, short films, and any other time
          a long work is included in an anthology or collection

         Technically, television shows and movies are to be italicized
          because individual scenes or episodes would be put in
          quotation marks. However, many times these titles are put in
          quotation marks and you will find this done quite often,
          especially in reviews
--snip--

https://www.sd43.bc.ca/school/gleneagle/Parents/LearningLab/Writing%20Your%20Way%20to%20Success/Citations%20and%20Sources/Titles%20Using%20Italics%20and%20Quotation%20Marks.pdf

> And...  But ok you are the maintainer and can do whatever you
> want, and break downstream people any way you like,

Stop whining.  You sound like humm.

> even for first class cititzens like references, without offering the
> possibility to somehow easily hook the real thing (the actual plain
> textual content) for them, like i did with mx-xr-url for example (to
> be able to finally provide external references also in PDF and HTML,
> not only in less(1)).

If you can articulate a concrete problem and provide a reproducer that
is independent of your mdocmx extension, I am prepared to entertain
revision and to reconsider my past decisions.

> And then it is always the mess with gnulib, and fiddling with the
> Makefile because i do not have texinfo installed, nor will i.

Now that groff's distribution archive ships the Texinfo manual in all
formats, this should no longer be a problem.  I've asked Bertrand to tag
and release 1.23.0.rc2 (about 12 hours ago), and since it will also
contain the gnulib snapshot that should solve both of these problems, if
not the ones arising from your use of groff mdoc(7) internals.

> So this is always a lot of distress, and for no value to me, since
> references extension will never be upstreamed with the current set
> of maintainers, fwiw.

I haven't looked at it, but I admit that the poor reviews it's gotten
from another groff developer doesn't recommend its urgency.

> Thanks for this info, however i want that mdocmx works with my
> groff clone that will spring into living existance when i live
> long enough, and there you will only find pdfmark.

Writing an extension against a baseline that doesn't exist is an
optimistic way to undertake software development.  Which doesn't mean
firms haven't death-marched their engineering staffs into it before.

It seems to me an unusual choice for a volunteer effort, though.

> I did not even know about pdf.tmac before this conversation!!
[...]
> .. and i stopped reading the diffs and commit messages.

pdf.tmac has been in groff since 2011.  I guess it's not just commit
messages and diffs you don't read.  For bonus points in this game you
can tell me how groff's man pages don't contain any of the useful
material from its Texinfo manual.

> The PDF created shows the same outline problem with mupdf as before.

You could consider creating a simple groff document, nothing to do with
mdocmx, that exhibits the same behavior.  Sharing it with us might help
us track down and fix the problem.  It's also possible the bug arises
from your own code.

> And mdocmx is still broken due to the Sx change, it is a mess with
> that doc thing, and further changes to be expected, unfortunately.
> With the September variant it just works fine.
> Just do not mind, i will somehow deal with it, maybe once when
> 1.23 is out.

At the risk of sounding like Bjarni, I commend to your attention a
foundational work in structured programming.

https://www.cs.utexas.edu/users/EWD/ewd02xx/EWD249.PDF

Don't expect robustness if you pierce the interface boundary and meddle
with a software module's _internal_ state or entry points.

Regards,
Branden

signature.asc
Description: PGP signature