Hi Alex, At 2023-01-04T20:03:08+0100, Alejandro Colomar wrote: > > There is more elaborate ASCII art in sched(7). That can be made > > relatively pretty with Unicode arrow characters; the four orthogonal > > single-stemmed arrows even happen to have portable special character > > identifiers going back to 1976 AT&T troff. > > > > But I'm not sure about chewing that one off. Using special > > character escape sequences would make the source looked weirder and > > misaligned. There's a way around that (the `tr` request) but that's > > a fairly chunky breach of the "no *roff requests in man page > > sources) rule that Ingo Schwarze and I try to hold to. > > > > Still, it's worth thinking about whether you'd like to have pic(1) > > diagrams in the Linux man-pages, with ASCII/Unicode-art fallbacks > > for terminal devices. > > I don't know. Can you show source code and formatted output of some > examples, so I can compare? Sure. groff's soelim(1) man page is an example. https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/soelim/soelim.1.man Here's the output of the first diagram in ASCII: input sourced file file | | v v preprocessor --> troff --> postprocessor | v output file ...and UTF-8: input sourced file file ⎪ ⎪ ↓ ↓ preprocessor ⎯→ troff ⎯→ postprocessor ⎪ ↓ output file ...and I'm attaching a screenshot from groff-man-pages.pdf. > > I have some pending patches that look like > > this. > > > > commit ab218d9f02bcfb9d6c7c127ed90c9a8c34cd8ba5 > > Author: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> > > Date: Wed Jan 4 02:31:37 2023 -0600 > > > > adjtimex.2, eventfd.2, mmap2.2, perf_event_open.2, quotactl.2, shmget.2, times.2, drand48.3, ldexp.3, random.3, tgamma.3, proc.5, mount_namespaces.7, random.7, sched.7, tcp.7, udplite.7, units.7, unix.7, utf-8.7: srcfix > > You could use "Various pages: srcfix" here. Cool, I'll do that, then. > BTW, another thing I noticed you practice is writing a trailing '.' in > the subject line. I don't have any strong preference there, but > followed the practice of not writing it, as Michael did. It has the > advantage of having one more byte for the subject. > > I guess you prefer language consistency. Yes, it's a practice I advocate to remind the commit writer that they should be writing a declarative _sentence_ in the imperative mood that characterizes the _intent_ of their change. Programmers, especially inexperienced, overwhelmed, or devious ones, tend to resort to passive description of their changes. This makes it harder to tell what their intentions were. (The final group views this as a feature, not a bug.) And anyone with a bit of salt knows--all too often, the effect and the intention of code all too often diverge. Then of course there are the rock stars who describe neither the intent or the actuality of their code at all--they just hand you demoware that "works", get a swift high-five from the manager, and hastily move on to another department. Leave documentation and validation to scullions, with the same manager marveling at the poor productivity of the rest of the team in contrast to the cowboy they just talked up for a promotion. Anyway, I belatedly remembered that Linux man-pages prefers to omit the trailing period, so my more recent proposed patches lack it. Regards, Branden
Attachment:
soelim-diagram.png
Description: PNG image
Attachment:
signature.asc
Description: PGP signature
