Re: [groff] mom manpage
rminal display is desired. A one-liner shell script if the 2nd example is too onerous to type. I honestly can't see how that's harder to access. Out of the usual place? No, just not in /usr/share/man. Documentation resides in other common locations. Are texinfo docs somehow not "usual?" Gratuitously? I selected xhtml for the mom docs after careful consideration. It served my purposes best. > You want HTML and PDF versions? Not a problem There is some irony in your dismissing html documentation, then acknowledging, as you do here, that some folks want it. > You want hyperlinking? Not a problem with .Xr links in modern > manual pages either. Linking wasn't a feature of manpages when mom was created. Switching to manpage format now just because linking is possible would be monumentally pointless. > You want bells, whistles, and moving gifs of cute cats? Bad idea, > documentation is about efficiently conveying information, not > about fluff and pictures and gimmicks. Not sure where you're getting your ideas about html documentation from. It is capable of moments of sobriety, you know. The online git documentation, for example, doesn't have any cute cats that I can see. Or bells, or whistles, or fluff, or gimmicks. At most, a some very helpful graphics. > Even moderately large systems can be beautifully documented in a > single manual page - for example, a shell. Which, by its very nature, is well suited to being documented in a manpage. The right tool for the job. Not the right tool for documenting everything. Insisting that manpages are the only true documentation format, elevating them to the point that become a measure of the quality of one's coding, runs counter to the Unix Rule of Diversity: distrust all claims for one true way. It's a good admonishment. > If is system is too large and a single page would become unwieldy, > yes, in the first step, you split it up to the next logical level > -i guess for mom that would be macros, but you can probably judge > better than i can what that next level is. That gives you too > many pages, most of them unreasonably short? So you form logical > groups of related macros, make one page for each group, and name > the page after the most important or typical macro of the group. I giggled. Honestly. What you've described has resulted in the sprawling mess of the groff manpages! To my mind, the most useful piece of information in groff(1) is "The groff info file contains all information on the groff system in a single document." Why? Because the info file is indexed and hyperlinked and I don't have to figure out whether groff(1), groff_font(5), groff(7), groff_char(7), groff_diff(7), nroff(1), troff(1), ditroff(1) or groff_out(1) has the information I'm looking for. From the command line, I can go straight to what I want. (For the record, I'm no fan of info.) Some programs simply are not well served by manpage-style documentation. Mom is one of them. Does that make her an example of bad coding (Doug's view on the subject)? Perhaps. Has she been successful at the purpose for which she was created? From my perspective, resoundingly yes. In addition to aiding her target users, mom is helping groff itself remain vital. > This is not rocket science and nothing new - just do it... ;-) Methinks you underestimate what would be involved. :) It wouldn't be the grunt work; it would be the conceptual reworking of the material, a daunting task for zero gain--and likely a loss--in utility. I haven't shirked creating a manpage for mom; I would prefer she didn't have one at all, other than, as proposed, one with a description, calling instructions, and a pointer to the html (and pdf) documentation. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] gratitude for man pages (was: mom manpage)
Colin -- On Tue, Dec 04, 2018, Colin Watson wrote: > One pleasant side-effect of this mild confusion is that I get > thank-you letters about man pages in general from time to time. > Here are a few samples, shorn of any personal information: That's wonderful! I was trying to make a point with my quips. I had no idea the outcome would be discovering this. Good on everyone who took the time to express their gratitude. Cheers. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
On Wed, Dec 05, 2018, James K. Lowden wrote: > On Tue, 4 Dec 2018 15:16:50 -0500 > Peter Schaffter wrote: > > > When I analyze my initial impression of manpages, I see that it > > was a clash between approaching computing from the humanities, > > as a non-programming user, versus approaching computing from the > > sciences, as a programmer. > > I don't think that's quite right, Peter. I suggest to you that's the > difference between a user guide and a reference manual. We need both, > always have, and the humanities have nothing to do with it, except > insofar as they teach clear exposition. I used humanities as a collective noun referring to users who come to a Unix system as philosophers, historians, linguists, writers of fiction, essayists... Such users do, generally, approach computing from a different perspective than sysadmins and programmers. They do not *think* like sysadmins and programmers. The filters they bring to bear on documentation are very much related to the issue at hand. Not to acknowledge that leads to BOFH thinking. Manpages target the B.Sc. crowd, not the B.A. crowd, if I may speak very broadly to make the point. I believe the latter tends to have the same reaction to manpages that I did on first exposure. "Manpage" implies "a manual." A common understanding of the term manual, the one brought to bear by my "B.A crowd," is "[A] comprehensive and step-by-step guide to a particular topic for both beginners and practitioners that also serves as a reference book. A manual details what is given and what is required, explains how to put the presented information into practice, and instructs how to solve problems as they occur." [BuinessDictionary.com] Manpages are the antithesis of this, so conceptual clashes of the sort I experienced are likely to occur. I'd hate to be guilty of extrapolating the general from the specific, but I'm certain I am not alone in my initial reaction to manpages. I do hope it's clear I am not attacking manpages or suggesting their content, style, or formatting be altered, except insofar as I'm Ingo's camp when it comes to mandoc. Manpages serve the needs of their target audience, of which I am a card carrying member. How well they do so will likely always be contentious, as, IMO, it should be; that's how we make them better. Nevertheless, they are not and will never be suitable for all documentation. I dispute the notion that if you can't document your work manpage style, your code is sub par. Classic case of "true in most instances, not in all." > You'd have a hard time convincing me that MOM is more complex > than troff itself, or that groff_mom(7) would be longer or > harder to organize than groff(7). Heaven forfend! I'd never suggest mom was more complex than troff. But she is nothing like g/troff. Groff is a typesetting *program*. Mom is, for all intents and purposes, a formatting *language*--as such, akin to html/css. Nowhere is html/css documented in manpage format, for the obvious reason that you can't learn a language from reading the dictionary. You need more than just "this is what the words mean." Organizing html/css into a usable manpage would, I think, prove a complex task indeed. _Ita quoque mom._ A better analogy might be GNU Lilypond, which provides a formatting language for engraving music. The language is not covered in a manpage because, quite simply, it cannot be, not in any meaningful way. Instead, its manpage does what I propose is best for mom: it gives the NAME, a DESCRIPTION, the invocation SYNOPSIS, and command line OPTIONS--the kind of information I want from a manpage, which I am likely to be consulting at the terminal because I intend to perform a command line operation. For actually creating lilypond documents, users are directed to the full manual. (I shudder to think of consulting a manpage for all that guile/scheme.) > The very fact that your HTML documentation is frequently viewed is > proof, actually, that a reference manual is needed. I see it differently. What it tells me is that mom users like consulting the documentation from their web browser. The experience is comfortable and familiar. Users don't have to go on the Web to consult the docs, which ship with groff, yet they persist in doing so. More a question of "familiarity breeds ease of use" than silent pleas for a manpage, I should think. :) -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
Bertrand -- On Thu, Dec 06, 2018, Bertrand Garrigues wrote: > As the html doc is de facto the current reference doc for mom (again, > I'm not arguing whether it's good or bad), I think the paragraph "4.6 > mom" in groff documentation should be modified. Changed entry per your request: diff --git a/doc/groff.texi b/doc/groff.texi index a6d1260..4526d3c 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -4649,11 +4649,26 @@ command line). @c XXX documentation @c XXX this is a placeholder until we get stuff knocked into shape -See the @cite{groff_mom(7)} man page (type @command{man groff_mom} at -the command line), which gives a short overview and a link to its -extensive documentation in HTML format. +Complete documentation for the @file{mom} macros is in html format. +@display +@file{/usr/share/doc/groff-base/html/mom/toc.html} +@end display + +An online version is also available. + +@display +@uref{http://www.schaffter.ca/mom/momdoc/toc.html} +@end display +PDF features and usage are covered in + +@display +@file{/usr/share/doc/groff-base/pdf/mom-pdf.pdf} +@end display + +See also @cite{groff_mom(7)} (type @command{man groff_mom} at the +command line). @c = @c = I'm not sure whether it's okay for entry points to local files to have literal paths or whether they need to be rendered symbolically for build/install purposes, so I won't commit without your go-ahead. > I think the online html doc could also be mentioned in > https://www.gnu.org/software/groff/; in the "Mission Statement" > paragraph, a .mom document is given as an example without a single word > on what the mom package is. Done, discretely. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
On Fri, Dec 07, 2018, Colin Watson wrote: > On Thu, Dec 06, 2018 at 06:38:40PM -0500, Peter Schaffter wrote: > > +@display > > +@file{/usr/share/doc/groff-base/html/mom/toc.html} > > +@end display > [...] > > +@display > > +@file{/usr/share/doc/groff-base/pdf/mom-pdf.pdf} > > +@end display > [...] > > I'm not sure whether it's okay for entry points to local files to > > have literal paths or whether they need to be rendered symbolically > > for build/install purposes, so I won't commit without your go-ahead. > > These paths are *very* Debian-and-derivatives-specific (even leaving > aside the hardcoded /usr/share/doc prefix, the split between groff-base > and groff is a Debianism), so they can't be committed upstream like > that. That's what I thought. > Either the local references will need to be omitted, or we'll > need some kind of arrangement along the lines of the existing > @HTMLDOCDIR@ and @PDFDOCDIR@ in groff's man pages (I'm not sure how > practical that is in texinfo). Neither am I. What I know about texifo wouldn't fit in a thimble. Bertrand, how do you feel about omitting the local docs, leaving just the pointer to the online docs? If you're agreeable, I can commit the change. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
On Fri, Dec 07, 2018, Ingo Schwarze wrote: > > Neither am I. What I know about texifo wouldn't fit in a thimble. > > You mean it would, right? Put it in there, and enough space will > probably be left to fit in my knowledge of textinfo, as well. Is the fact the we both mistyped 'texinfo' evidence our of shared disdain? > So indexing is actually much better with manual pages, and > searching doesn't work at all with HTML. It could equally be said that *an* index (i.e. a categorized, linked list of terms) is much better with html, and searching inside displayed manpages leaves much to be desired. The issue isn't which format is better, rather which is more apt. Some programs are better served by documentation in a format other manpages. Mom is one of them. The 1.x release documentation addressed the issue explicitly: "Some mom users are sure to ask: “Why is the documentation in html? If mom’s so great, why not pdfs to show her off? And if groff’s so great, why not write a man page?” ... The documentation is in html because I still find it the best tool for navigating lengthy manuals. Html, with its anchors and links, came into being precisely so people could do something they’d never been able to with the printed word: instantly track down internal and external references in a document. It’s essential that people reading mom’s documentation never have difficulty finding precisely the macro they need for a particular task. Equally, when reading up on a macro, they should never be presented with terms or other macro names for which they cannot instantly find accurate explanations. Short of having written the documentation in TeX for the info browser (and TeX bloat is one of the reasons I prefer to typeset with groff), I can think of no better way to achieve the kind of truly useful documentation I wanted than html." > I'm sorry i'm not very constructive today, but i don't know how to > fix the texinfo problem either. As Betrand has pointed out, the awkwardly-named POSITIONS FROM INSTALLATION in groff(1) takes care of the problem. > But one thing is certain: linking to the WWW more prominantly than > to the local documentation, or in a way that is less likely to > fail for the user, is a very bad idea. What the user finds on the > Web may not even correspond to the version of the software that is > actually installed. I develop mom independently of groff. An unfortunate but inevitable consequence is that mom releases occur more frequently than groff releases. You're quite right: the online documentation may not--in fact can be expected not to--correspond to the installed documentation. It supersedes the installed documentation--another reason why an attempt to render it as a manpage is ill-advised. Users who install a version of mom newer than what's installed with groff are stuck with an out-of-date manpage until the next groff release. Taking this into account, I propose diff --git a/doc/groff.texi b/doc/groff.texi index a6d1260..f588d5f 100644 --- a/doc/groff.texi +++ b/doc/groff.texi @@ -4649,11 +4649,36 @@ command line). @c XXX documentation @c XXX this is a placeholder until we get stuff knocked into shape -See the @cite{groff_mom(7)} man page (type @command{man groff_mom} at -the command line), which gives a short overview and a link to its -extensive documentation in HTML format. +The main documentation files for the @file{mom} macros are in html +format. Additional, useful documentation is in pdf format. See the +groff(1) manpage "Collection of Installation Directories" for their +location. +@itemize @bullet +@item +@file{toc.html} +@noindent +Entry point to the full mom manual. + +@item +@file{macrolist.html} +@noindent +Hyperlinked index of macros with brief descriptions, arranged by +category. +@item +@file{mom-pdf.pdf} +@noindent +PDF features and usage. +@end itemize + +The mom macros are in active development between groff releases. +The most recent version, along with up-to-date documentation, is +available at +@uref{http://www.schaffter.ca/mom/mom-05.html} + +See also @cite{groff_mom(7)} (type @command{man groff_mom} at the +command line). @c = @c ========= If all are agreeable and my .texi formatting is acceptable, I can commit this. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
On Tue, Dec 11, 2018, Ingo Schwarze wrote: > At this point, i think the full cleanup Peter intends to do is > better delayed until after release. Agreed. IIRC--I'm too lazy to look--I started the thread by saying it was a low priorty issue. :) > A small patch clarifying, within the manual page itself, what the manual > page is, and what it is not, as far as Peter thinks that is useful and > currently lacking, would be OK before release, i think, because a > small patch to a manual page is unlikely to cause a distraction to > release preparation work and almost certainly won't break the build > or introduce a bug. The manpage as it is covers this prominently enough I think. No need to change it for the release. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom manpage
Branden -- On Tue, Dec 11, 2018, G. Branden Robinson wrote: > I'm happy to aid with the maintenance of groff_mom(7), as my > predilections and neuroses seem to have led me to stumble into an > unofficial role as a groff man page editor, but a synoptic view of > mom is beyond my current competence. I'm sometimes wonder if it isn't beyond mine, too. :) -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom: blockquotes lose indent across page breaks
John -- On Mon, Dec 17, 2018, John Ankarström wrote: > I've run into a fairly annoying bug in the mom macro package: if > I let a blockquote run across multiple pages, it will be indented > only on the first page. > > Like this: > > Here begins my blockquote, with normal indentation. > But here comes a page break: > > --- > > Now the blockquote continues, but the indentation > has been lost! > > Does anyone know of a way to fix this? I'm not seeing the problem at this end with the most recent version of mom, so which version of mom are you using? If it's recent, pdfmom -z -dVERSION=1 foo at the prompt should spit it out. If that returns nothing, look in the file 'om.tmac'. The version is just underneath the copyright notice. If your om.tmac is stock, it should be located at /usr/share/groff/tmac/current/om.tmac If you've downloaded mom from her website, look inside the om.tmac you're currently using. Cheers. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom: blockquotes lose indent across page breaks
On Mon, Dec 17, 2018, John Ankarström wrote: > However, now I'm faced with another problem: the .BIBLIOGRAPHY > macro doesn't seem to work. This code used to create a nice, > capitalized heading right in the center, followed by my > accumulated bibliography: > > .HEADER_CENTER "Bibliografi" > .BIBLIOGRAPHY_STRING "Bibliografi" > .BIBLIOGRAPHY_STRING_UNDERLINE OFF > .BIBLIOGRAPHY > .QUAD L > .[ > $LIST$ > .] > .BIBLIOGRAPHY END > > Now, all I get is a smaller, left-aligned uncapitalized heading with no > bibliography following. An overzealous cleanup of the LIST macro, which used in the generation of bibliographies, is the culprit, plus a hard-to-spot typo in the title-quad section of bibliography setup. The title is no longer in caps by default, nor is it underlined. If you want caps and/or underlining, you have to enable it. Also, the addition of a HEADER_CENTER to bibliographies requires explicitly enabling it. Here's what you want: .HEADER_CENTER "Bibliografi" .BIBLIOGRAPHY_HEADER_CENTER .BIBLIOGRAPHY_STRING "Bibliografi" .BIBLIOGRAPHY_STRING_CAPS .BIBLIOGRAPHY .[ $LIST$ .] .BIBLIOGRAPHY END I've updated mom-2.4.tar.gz on mom's website, so you can grab the fixed om.tmac from there. -- Peter Schaffter http://www.schaffter.ca
[groff] Push mom fix?
Branden -- I'd like the bibliography/refer fix to mom to be in the upcoming release. On my end, regression tests check out and the sample docs build fine. Okay to push, or will that mess things up? -- Peter Schaffter http://www.schaffter.ca
Re: [groff] Push mom fix?
On Mon, Dec 17, 2018, G. Branden Robinson wrote: > At 2018-12-17T20:56:53-0500, Peter Schaffter wrote: > > Branden -- > > > > I'd like the bibliography/refer fix to mom to be in the upcoming > > release. On my end, regression tests check out and the sample docs > > build fine. Okay to push, or will that mess things up? > > Bertrand is the person to ask, as he's the release manager. Sorry. I meant to address Bertrand. Your names have an awful lot of letters in common. :) -- Peter Schaffter http://www.schaffter.ca
Re: [groff] mom: blockquotes lose indent across page breaks
On Tue, Dec 18, 2018, Ingo Schwarze wrote: > Hi Peter, > > Peter Schaffter wrote on Mon, Dec 17, 2018 at 08:55:04PM -0500: > > > I've updated mom-2.4.tar.gz on mom's website, > > Never change tarballs after they are released. > That causes bad trouble to downstream packagers: The tarballs aren't, and never have been, for packagers. The "distinct from groff" nature of mom development means that any "packaged" version will be the one from contrib/mom when groff is built. Tarballs are posted so users can update mom without having to pull groff from the development branch. The two (i.e. contrib/mom and the tarballs) are always in synch, but packagers are not expected to use the tarballs, and indeed, none have. Every once in a while, as presently, mom presents a bug whose fix is so small that it doesn't warrant a version change but does need to be made available to run-of-the-mill users immediately. A patch applied to version N.N rather than a release of version N.N-x, as it were. In such cases--extremely rare--the patch is applied to the development branch of groff/contrib/mom and the "users' tarball" is silently updated. Since no one is packaging mom for shipment separately from groff, concerns about downstream packaging aren't relevant. Mom began life entirely separate of groff because of groff's slow release cycle. I got a couple of requests from Debianites wanting to package her, and a proposal from Werner that she become part of groff. I chose the latter despite the headache of the groff-packaged version perpetually lagging behind the latest mom release, a problem solved by posting the tarballs. Though mildly unconventional, this pragmatic solution has worked without a hitch for over ten years. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] GNU troff version 1.22.4
On Sun, Dec 23, 2018, Bertrand Garrigues wrote: > After a last commit (copyright year displayed on 'groff --version'), > I've created tag 1.22.4 and pushed the official package on GNU ftp. > Below is the annoucement done on the GNU info mailing list. > > I just need to make a few update on the groff website. > > Many thanks to everyone who contributed, tested and reported bugs. Congratulations are in order. I can't recall the last time there was so much activity prior to a release. I add my voice to Bertrand's thanks. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] Groff and poor font rendering
Kevin -- On Mon, Mar 11, 2019, Kevin Moses wrote: > I seem to have no problem printing clear readable fonts with > my printer when the PDF file is generated by, for example, an > ebay shipping label. However, any pdf file that I create with > say, pdfmom -P-e example.mom > new.pdf results in a decent page, > but still clearly pixelated, and certainly not as sharp as more > conventional google doc files, etc. Does the pixelation show up in your pdf viewer, when you print out a copy, or both? Bad rendering at the screen could be a sign of a misconfigured viewer. Try several viewers and see if the problem persists in all of them. I'm unfamiliar with Void Linux. Can you possibly test with another distro? If I understand correctly, Void is "from scratch." Its font handling may well be the source of your problem. If you haven't got access to another distro, could you attach a small source file and its pdf along with the command line you used to build it? -- Peter Schaffter http://www.schaffter.ca
Re: [groff] Does the groff -ms implementation have a way to switch to a new column in .2C mode?
On Thu, Jun 06, 2019, T. Kurt Bond wrote: > The context is that I've got a part of my text that needs to stay together, > and it is being split across columns, so I need to switch the column before > that part starts. I have used a .br and .ne X, where X is guesstimate at > the lines needed, but wondered if there was a cleaner approach. If, instead of -ms, you used the mom macros, you could accomplish this cleanly with .COL_NEXT. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] In text references: optional page numbers?
Paul -- On Fri, Jun 14, 2019, Paul Swanson wrote: > Using groff, refer and the ms macros, I can't figure out how to > achieve in text references with optional page numbers. > > Here's what I'd like to achieve. > > Sometimes, I need to reference a given work in its entirety: > > ... and thus all is foo bar (Smith 1984). > > Other times, I need to quote the same author / source directly: > > ... "and thus all is foo bar" (Smith 1984, p. 42). > > I can't figure out how to create an in text reference that will > behave like that. Have a look at http://www.schaffter.ca/mom/momdoc/refer.html#parenthetical for a discussion of parenthetical references in text. It covers what you want. It's part of the mom macros' documentation but it's not mom-specific, just refer usage explained more approachably than the refer(1) manpage. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] Unicode fonts output
On Tue, Aug 06, 2019, Deri wrote: > Two problems:- > > One, my "solution" used underscores when it should have used > hyphens, so the "magic" is "U-"!! I was about to mention this when your post appeared. :) > Two, I have found, in your example, the .FAMILY line needs to come > after .START. Yes, but not quite. The correct place is after .PRINTSTYLE but before .START. PRINTSTYLE wipes out any family, point size, leading, etc. directives that come before it and replaces them with default formatting. Therefore, global changes to a doc's type parameters are only respected if they come after PRINTSTYLE (and before START), as described here: https://www.schaffter.ca/mom/momdoc/docprocessing.html#type-before-start -- Peter Schaffter http://www.schaffter.ca
Re: "mom": How to transition from two columns back to one?
Steve -- On Tue, Dec 17, 2019, Steve Ross via wrote: > Is there a way in "mom" to force it to (more or less) evenly fill > both columns with text and then exit back to a single column mode? Yes and no. :) It's a little hard to grasp precisely what you want from your ASCII representation, but assuming a page that has 2-column text at the top with some single-column, full-measure text underneath, you first have to balance the columns yourself using .COL_NEXT or .COL_BREAK. At the spot you want to break out of column mode, enter .SP .rr #COLUMNS .L_MARGIN \n[#DOC_L_MARGIN]u .LL \\n[#DOC_L_LENGTH]u Subsequent text will be over the full measure. If you wish to return to 2-column mode *on the same page*, enter .SP .nr #COLUMNS 1 .nr #COL_NUM 1 .L_MARGIN \n[#DOC_L_MARGIN]u .LL \n[#COL_L_LENGTH]u .COL_MARK If you wish to *break to a new page* after the full-measure text and reinstate 2-column mode, .nr #COLUMNS 1 .nr #COL_NUM 1 .LL \n[#COL_L_LENGTH]u .NEWPAGE .rr #NEWPAGE -- Peter Schaffter http://www.schaffter.ca
Re: "mom": How to transition from two columns back to one?
Steve -- On Mon, Dec 23, 2019, Steve Ross wrote: > As a follow-up question, and after the above commands, why does > \n[#DOC_L_LENGTH] > return the value of DOC_L_LENGTH (e.g., 468000) in machine units while, > for example, both > \n[#LL] > and > \n[LL] > return the value of zero? > And likewise for, for example, > \n[#QUOTE_INDENT] > and > \n[QUOTE_INDENT] > I think that I don't understand how to access the LL and > QUOTE_INDENT registers. They return zero because mom doesn't set any of these registers. The register set by '.LL' is \n[#L_LENGTH]. The register set by '.QUOTE_INDENT n' or '.QUOTE_STYLE INDENT n' is \n[#Q_OFFSET_VALUE]. Unless you're doing something fancy, there's no need to access directly any of mom's registers. Registers used by mom are entirely set via macros. Fundamental to mom's design is moving everything into macro space, as opposed to the classical macro sets, which require manipulating registers and strings at the groff request level. -- Peter Schaffter http://www.schaffter.ca
Re: How to use refer macros-agnostic way?
On Wed, Jan 08, 2020, Tadziu Hoffmann wrote: > In my opinion, the manual page [refer(1)] is perfectly adequate, > if you accept that it is not a tutorial but rather a reference > manual that you refer to for particular details of implementation > or invocation. The caveat is significant: you must accept that manpages aren't instruction manuals, which term I prefer to "tutorial," which has a whiff of condescension. They're more like abstracts with cheat sheets. > In fact, all of the manual pages for troff-related utilities > assume that you're already familiar (at least in very broad > terms) with the basic ideas of how the utilities are meant to be > used. A classic manpage Catch-22: useful only after you already know what you turned to the manpage to learn. I disagree that refer(1) is perfectly adequate: * there's no mention that the mom macros, which have been part of groff for close to twenty years, are suitable for use with refer; * the wording of the preamble to the list of field identifiers creates the impression that they are the only ones available; * there is no mention that the number of reference types can be extended beyond the four that are listed; * sections dealing with accent strings in bibliographic databases need to be updated to state first that accented characters should be entered as named glyphs, reflecting contemporary usage, and only secondarily that accent strings, if preferred, should come after the affected character. I thoroughly sympathise with the OP's frustration with the refer manpage, even if there's nothing to be done about it. It's complete and accurate, but communicates its substance poorly to all but the initiated. It would be of enormous help if, at the very least, the SEE ALSO section pointed readers to Lesk's paper so they don't have to plough through the whole manpage only to discover that they're as befuddled and befogged as before, with no clue where to find the kind of helpful information they were seeking. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] 02/07: **/*.man: Put subsection heads in sentence case.
On Fri, Jan 31, 2020, John Gardner wrote: > Personally, I prefer headings to be written in sentence-case, and > title-case limited to *literal* titles: the name of a book, movie, song, > album, etc. Ergo, .SH and .SS are better off sticking to sentence-case, if > just to eliminate the mental overhead of remembering which words to > capitalise and which not to. I concur. Titles--including chapter titles--get title case, headings should get sentence case. It really does look better that way. -- Peter Schaffter http://www.schaffter.ca
Re: she's it, not her ...
On Fri, Feb 07, 2020, Ingo Schwarze wrote: > Oh well. A German attempting to educate a French about the > English written by a Canadian who lives in Ontario and Quebec > and was born in Costa Rica. What could possibly go wrong? I love this. BTW, I accidentally replied to Marc off list, explaining the rationale behind "she" in the momdocs. He replied with corrections to my (French) grammar. May the circle continue... -- Peter Schaffter http://www.schaffter.ca
Re: mom: .START macro resets page dimensions
On Mon, Mar 23, 2020, Serge Baumer wrote: > In the om.tmac, the .START macro calls .DEFAULTS unconditionally. Here > are few lines of code from the very beginning of the .DEFAULTS > definition: > > .if !\\n[#DOC_TYPE]=5 \{\ > . ie !d $PAPER .PAPER LETTER > . el .PAPER \\*[$PAPER] > .\} > > They are introduced by a commit dated 2018-03-04 to replace the more > simple > > .if !d $PAPER .PAPER LETTER > > Thus, the new code is in the official 1.22.4 but not in earlier groff. > > So, what we get here if we're not making slides (i.e. #DOC_TYPE != 5) > but have used .PAGE or any of .PAGEWIDTH, .PAGELENGTH separately before > .START. If we haven't used .PAPER yet, it's called here with "LETTER", > resetting our custom page dimensions. But if we'd called .PAPER, say, > before making page size tweaks: it's called again now, destroying our > previous work all the same. So, we have a chance to setup our own page > size only with slides. It's astounding how long a bug like this can hang around before it's discovered. There are two culprits. The first is that mom has been setting the default papersize (letter) in om.tmac itself with '.PAPER LETTER' when she should be calling PAGEWIDTH and PAGELENGTH separately. The second is that the DEFAULTS clause, above, is unnecessary. It's cruft from testing that I neglected to remove. When these issues are corrected, PAGELENGTH, PAGEWIDTH, and PAGE behave as expected. One thing to be wary of: PAGEWIDTH only sets the width of the physical page. It does not in/decrease the line length (an assumption mom does not make), and must be done either by giving an explicit R_MARGIN or an explicit LL. > I didn't report this as a bug because I'm not sure that here's no > some sort of planned behaviour and that I didn't miss some info. > I can create a ticket though. It is a bug. No need to create a ticket. Most mom bug reports come to me directly and go into the BUGS file. I'll make the necessary changes to the om.tmac in the groff repo and to the tarball at the mom site within a day or two. If you're in a hurry, you can make the changes yourself. Search through om.tmac for the text "Set up a default papersize". Remove the line beneath, '.PAPER LETTER', and replace it with .PAGEWIDTH 8.5i .PAGELENGTH 11i then remove entirely the clause in DEFAULTS, above. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] [mom] blockquote indent breaks
On Wed, Mar 25, 2020, Marcus Atilius Regulus wrote: > When I change the value of BLOCKQUOTE_INDENT (which > I need since I usually set PARA_INDENT 0) and > it wraps to another page, the indent breaks. Thanks for reporting this. The fix will be in the mom 2.4-4_a bugfix release, which I hope to make available over the weekend. Your timing is fortuitous. I was planning to do the release a couple of days ago but COVID-19 disruptions prevented it, so I can include the indent fix. > Replacing /usr/share/groff/1.22.4/tmac/om.tmac with > the om.tmac from mom-2.4-4.tar.gz from > https://schaffter.ca/mom/mom-05.html#version-2.4-4 > gives > ! SyncTex Error : No file? No idea what's causing this. 2.4-4 from the tarball works fine at my end. I don't use synctex. At what point in your toolchain is it invoked? A normal groff document build has nothing to do with TeX. I've read reports of the Evince document viewer spitting out the message, but that is not a groff or mom issue. -- Peter Schaffter http://www.schaffter.ca
Re: [groff] [mom] documentation typo single-quote inline
On Fri, Mar 27, 2020, Marcus Atilius Regulus wrote: > There seems to be a typo in mom's documentation: > https://schaffter.ca/mom/momdoc/inlines.html#inline-characters-groff > > It says: > Open (left) single-quote\[oq] > Close (right) single-quote \[oq] > > should be imo: > Close (right) single-quote \[cq] Thanks. I do like a good pair of eagle eyes. -- Peter Schaffter http://www.schaffter.ca
Re: mom footnote belonging to a Heading
Heinz -- On Sun, Mar 29, 2020, Heinz-Jürgen Oertel wrote: > I have a need to place a foote note to a HEADING, but can not manage it. > Any hint for me? > > example: > > .HEADING 1 "Aus der Dobrudscha und Bessarabien" > .FOOTNOTE > Dieser Teil erschien im Jahrbuch 1963 ab Seite 173 > .FOOTNOTE END > .HEADING 2 "Deutsches Leben am Schwarzen Meer: was lehrt Sarata?" Mom's HEADING macro cannot natively accommodate footnotes because the break after each line of heading text is hardwired in. IOW, \c as the last character of heading text has no effect; it does not join the footnote marker to the head, but rather plants it at the beginning of the next line of regular text. As a workaround, insert this code at the top of your file: am HEADING .ev HEADING .vpt 0 .sp -1 .vpt .nop \v'-\\*[$HEAD_\\n[#LEVEL]_BASELINE_ADJ]'\h'\w'\\$1'u'\c .. This allows adding a footnote to any heading level provided that - no \c is attached to the heading text - the footnote is terminated with .FOOTNOTE END BREAK Text after a HEADING or a HEADING+FOOTNOTE must be a PP, EPIGRAPH, QUOTE, BLOCKQUOTE, CODE, or another HEADING. If not, insert .br .ev 0 after the HEADING. Example: .HEADING 1 "Aus der Dobrudscha und Bessarabien" .FOOTNOTE Dieser Teil erschien im Jahrbuch 1963 ab Seite 173 .FOOTNOTE END BREAK .PP Paragraph text. .HEADING 2 "Deutsches Leben am Schwarzen Meer: was lehrt Sarata?" .br .ev 0 Text not introduced by PP. I'm not sure how robust this is, though it works well in the testing I've done. -- Peter Schaffter http://www.schaffter.ca
Re: mom footnote belonging to a Heading
On Mon, Mar 30, 2020, Heinz-Jürgen Oertel wrote: > Am Sonntag, 29. März 2020, 22:04:57 CEST schrieb Peter Schaffter: > > On Sun, Mar 29, 2020, Heinz-Jürgen Oertel wrote: > > > I have a need to place a foote note to a HEADING, but can not manage it. > > > Any hint for me? > > > As a workaround, insert this code at the top of your file: > > > > am HEADING > > .ev HEADING > > .vpt 0 > > .sp -1 > > .vpt > > .nop \v'-\\*[$HEAD_\\n[#LEVEL]_BASELINE_ADJ]'\h'\w'\\$1'u'\c > > .. > > > > This allows adding a footnote to any heading level provided that > > > > - no \c is attached to the heading text > > - the footnote is terminated with .FOOTNOTE END BREAK > > > > Text after a HEADING or a HEADING+FOOTNOTE must be a PP, EPIGRAPH, QUOTE, > > BLOCKQUOTE, CODE, or another HEADING. If not, insert > > > > .br > > .ev 0 > > > > after the HEADING. > > works not perfect, sorry, attached the result as screen shot. > You see the foot note number just behind the capital letter 'B' You neglected to say you were centering your headings. :) The following amended code should take care of the problem: .am HEADING . ev HEADING . shift \\n[.$]-1 . vpt 0 . sp -1 . vpt . nr heading_w \w'\\$1' . nr center_i \\n[.l]+\\n[.i]-\\n[heading_w]/2 . if \\n[.ce] .in \\n[center_i]u . nop \h'\w'\\$1'u'\v'-\\*[$HEAD_\\n[#LEVEL]_BASELINE_ADJ]'\c .. A minor annoyance to this is that you must pop the HEADING environment explicitly after the footnote: .HEADING 1 "Aus der Dobrudscha und Bessarabien" .FOOTNOTE Dieser Teil erschien im Jahrbuch 1963 ab Seite 173 .FOOTNOTE END BREAK .ev .PP Begin paragraph text... Please test. Further tweaks may be required. -- Peter Schaffter http://www.schaffter.ca
Re: mom footnote belonging to a Heading
On Mon, Mar 30, 2020, Heinz-Jürgen Oertel wrote: > Am Montag, 30. März 2020, 09:47:17 CEST schrieb Heinz-Jürgen Oertel: > > I did, and now it looks very good for me. For now it's a good > > solution for me. > > I did not look close enough, only for the heading and the > footnote. Sorry. After a Heading now all paragraphs are indented > to the start of the centered heading, All first lines of a PP > paragraph are correct, but the following lines are intended. This > changes after a a new page begins. On the next page all paragraphs > are correctly formatted. I have attached a picture. The only way I can reproduce this is by neglecting to pop the environment after a heading, which makes sense. For various reasons, the workaround needs an indent to attach footnote markers to centered heading text. If the environment isn't popped, the indent remains active. Mom herself pops the environment after printing the page header, which is why the indent disappears after a page break. The workaround cannot take care of popping the environment because, of necessity, it terminates with the "join to next line" character, \c, needed to attach the footnote marker. Can you confirm that you have used the following template style for entering all your headings after including the workaround? .HEADING 1 "Heading with footnote" .FOOTNOTE Footnote text .FOONOTE END BREAK .ev \" Pop env. .PP Paragraph text... .HEADING 1 "Heading without footnote" .br \" Add break .ev \" Pop env. .PP Paragraph text... If you have and the problem persists, try explicitly setting the environment to zero, i.e. '.ev 0', after the HEADING. If that still leaves you with indented paragraphs, I will have to see more of your source file to track down the problem. -- Peter Schaffter http://www.schaffter.ca
Re: Proposed: drop groffer (was: contrib/groffer/roff2.1.man)
On Tue, Apr 21, 2020, Ulrich Lauther wrote: > Maybe I am not qualified to contribute my opinion, as I never used groffer. Same here. I've never used groffer. Seems superfluous. -- Peter Schaffter http://www.schaffter.ca
Re: Potential enhancements to install-font.sh from https://www.schaffter.ca/mom/bin/install-font.sh
On Mon, Apr 27, 2020, T. Kurt Bond wrote: > Today I finally took the time to figure out how to install groff fonts using > the shell script https://www.schaffter.ca/mom/bin/install-font.sh . > > It was way easier than following the manual steps. > > In doing so I made some changes to script that made it easier for me to > use. I'm sending this e-mail so folks can look at the changes and see > if they would be useful in general. > > I changed the documentation of the -l and -s options to refer to the > prefixes /usr/local/share/groff and /usr/share/groff respectively > because those are the directories they actually use. Good. > I added a -P option that lets you specify the prefix to use. I often > install software into places like /sw/versions/groff/git (so I can > have multiple versions of software installed), which means > that the I'd specify "-P /sw/versions/groff/git/share/groff". Needs better documentation. -P dir Path to the top-level groff directory if groff has been installed in a non-default location. > I added a -n option that stops the source font file from > being installed anywhere. This is useful if you don't have > /usr/local/share/fonts/truetype or /usr/local/share/fonts/opentype > or /usr/local/share/fonts/type1, which, if you didn't specify -C > and depending on the type of font file, is where the source file > is copied to. Okay. Does the same thing as answering "n" to the prompt that asks whether to copy, but might be useful for batch processing. > I changed the script so it checks if has write access to the > prefix directory specified, rather than checking if it is running > as root, because if you've installed groff into a location you > have access to as a normal user it will be writable. And if you > are running it as root it will also be writable. Good. > I also moved the check after the parsing of the command line > options, so it uses the user specified prefix directory, whether > that was set with -l or -s. Good. > Also, wouldn't this script be useful to include in the groff > distribution? I'm inclined to think so, however it contains non-portable bashisms and so might not be appropriate. The script was a quick and dirty solution to font installation. Something similar but more robust and not reliant on a particular shell interpreter would be better. -- Peter Schaffter http://www.schaffter.ca
Re: Potential enhancements to install-font.sh from https://www.schaffter.ca/mom/bin/install-font.sh
On Tue, Apr 28, 2020, T. Kurt Bond wrote: > Peter Schaffter wrote: > > On Mon, Apr 27, 2020, T. Kurt Bond wrote: > >> I added a -P option that lets you specify the prefix to use. I often > >> install software into places like /sw/versions/groff/git (so I can > >> have multiple versions of software installed), which means > >> that the I'd specify "-P /sw/versions/groff/git/share/groff". > > > > Needs better documentation. > > > > -P dir > > Path to the top-level groff directory if groff has been > > installed in a non-default location. > > Yes, that is much better. I've attached a patch against the original > install-font.sh versus a version with that change made. Patches applied. Revised install-font.sh has been uploaded to the mom website.
Re: Potential enhancements to install-font.sh from https://www.schaffter.ca/mom/bin/install-font.sh
On Wed, Apr 29, 2020, James K. Lowden wrote: > On Tue, 28 Apr 2020 17:45:46 -0400 > Peter Schaffter wrote: > > Something similar but more robust and not reliant on a particular > > shell interpreter would be better. > > I just took a look, Peter, because I have some experience writing > Bourne shell scripts. I don't see anything bash-specific, just > looking over it. You might just change #!/bin/bash to #!/bin/sh; > I think it will run pretty well, maybe perfectly. On Debian derivatives, dash(1) has a bug in its signal handling, hence !#/bin/bash rather than the generic !#/bin/sh. In turn, bash(1) requires the bash-specific 'set -o posix' in order for ctrl-C to work. -- Peter Schaffter http://www.schaffter.ca
Re: Potential enhancements to install-font.sh from https://www.schaffter.ca/mom/bin/install-font.sh
On Wed, Apr 29, 2020, James K. Lowden wrote: > On Tue, 28 Apr 2020 17:45:46 -0400 > Peter Schaffter wrote: > > > > Also, wouldn't this script be useful to include in the groff > > > distribution? > > > > I'm inclined to think so, however it contains non-portable bashisms > > and so might not be appropriate. The script was a quick and dirty > > solution to font installation. > > That's the best and biggest Q&D shell script I've ever seen. Perhaps I should have said "...started off as a quick and dirty solution." :) -- Peter Schaffter http://www.schaffter.ca
Re: Groff macro to make .UR and .UE links clickable in PDF?
On Tue, Jun 16, 2020, Steve Izma wrote: > Anyway, my strategies for typesetting for a printed document: Excellent advice, well reasoned and well presented. I would add that inserting \: (the zero-width break point) before or after every forward slash in a URL, depending on the style guidelines of a document, saves a lot of manual fiddling when URLs must be broken across lines. Not all the fiddling, but enough to warrant making it a first line of defence. -- Peter Schaffter http://www.schaffter.ca
Re: \: re-enables hyphenation--should it?
On Fri, Jul 31, 2020, Dave Kemper wrote: > \& has no effect on breaking (nor is it documented to). "Zero-width > space" is kind of a misnomer for it, I guess. CSTR #54 called it a > "zero width filler character"; the term "zero-width space" for it > seems specific to the Texinfo document. Surely the most useful and accurate way to describe \& is "a zero-width, non-printing character." -- Peter Schaffter http://www.schaffter.ca
Re: Groff vs Heirloom troff (was Re: Quick question: how to do .index in groff?)
On Fri, Jul 31, 2020, Steve Izma wrote: > For almost everything I typeset, especially books and > newsletter-type publications, I always at least a few places > where I need to use track kerning on a paragraph in order to get > good word spacing and to shorten or lengthen paragraphs in order > to avoid widows (the last line of a paragraph starting a column > of text). When I adjust the kerning (or mortising, if necessary) > in values of one-hundredth or one-thousandth of a point, it can > make a difference in whether a word fits on a line or is broken > or pushed to the next line, thereby making the paragraph too > long. I avoid trying to adjust only part of a paragraph because > that can drastically affect the "colour" (i.e., density) of the > text. Ditto. This was "how the pros did it" 40 years ago when I was apprenticing in a type shop, and it's still the way they do it. No programme, application, or algorithm can produce typographic results as good as those that have been fine-tuned by a human. The finer the tuning--i.e. line-by-line--the better the result. > That said, I've never been convinced that paragraph-at-a-time > justification makes a difference to the work I need to do for > getting good word fits and even colour to the page. Based on my own experience, I agree. Sure, with the KP algo you almost never get widows, but that doesn't mean the typographic strategies used to achieve this golden state are always satisfactory. > ...I would like to caution people who think that the > implementation of that algorithm [Knuth-Plass] in groff is going > to lessen the effort that goes into high-quality typography. Again, I agree. Several years ago, I fielded the idea that, instead of chasing after the Grail of paragraph-at-once, groff's line-formatting algorithm be improved instead. I worked on systems that used the formatting strategy I proposed https://lists.gnu.org/archive/html/groff/2014-03/msg00322.html and can confirm that it significantly reduced the amount of intervention required to achieve good grey on a line-by-line basis. There wasn't much interest in the proposal back then--I felt a bit like a voice crying in the wilderness--but maybe it's time to try crying again? -- Peter Schaffter http://www.schaffter.ca
Re: install-font.sh -P needs to allow dots in its argument.
On Sun, Aug 02, 2020, T. Kurt Bond wrote: > The linux version of homebrew installs groff's data directory in > /home/linuxbrew/.linuxbrew/share/groff by default. > > I must have cargo culted the check_optarg without checking everything out > when I added the -P option. I've attached a patch to install-font.sh to > make it check that the argument to -P is a directory and that it is > writable. Good. Thanks. Patch has been applied to install-font.sh on the mom website. > I kept the check that the argument doesn't start with a dash, even though > someone evil might start their directory with a dash. Should that check be > dropped? Bash parses getopts in a rudimentary fashion that doesn't distinguish between an option and an argument. Given the choice between checking for evil (starting a dirname with a dash) and checking for absentmindedness (forgetting to supply the dirname), better to opt for the latter. Although these days it sometimes doesn't seem so, there's far more absentmindedness in the world than evil. :) -- Peter Schaffter http://www.schaffter.ca
Re: (off topic?) Docbook? Re: manlint?
On Sun, Sep 27, 2020, James K. Lowden wrote: > I think the idea behind grothml is that one input document "just works" > with any backend. A different -- and, I would argue, more > realistic -- approach would be a macro-to-HTML converter that worked > only for documents expressly written with HTML in mind, using only > macros and eschewing troff requests. Such a document is, I assert, > easily converted to HTML and produces perfectly acceptable PDF. Yes. I do this frequently with -mom. It's almost trivial. It doesn't require much more than a couple of sed scripts. > Almost any macro set you pick maps onto HTML Precisely. FWIW, the mom macros were designed with conversion to other "...ML" formats in mind. Almost all typesetting functions are performed with macros even when groff has requests to accomplish the same thing; equally, the most common inline requests are treated as string-invoked macros. (The goal was to insulate users--and documents--as much as possible from low-level troff.) Semantic elements are all unambiguously associated with a macro. Every semantic macro has corresponding style macros, which can be converted to stylesheets. PDF linking has a clear syntax that allows unambiguous creation of ids for internal linking and a dedicated macro for external links. For all that, if I know a document is likely to be converted to HTML, I make sure the document is written sensibly for the conversion--exactly what James proposes. It's admittedly easy with -mom, but I see no reason why -ms documents intended for HTML output can't be written specifically for it using the available macros. Nothing wrong with asking document writers to shoulder some of the burden. -- Peter Schaffter http://www.schaffter.ca
Re: (off topic?) Docbook? Re: manlint?
On Mon, Sep 28, 2020, Steve Izma wrote: > I think Larry's point here is that it's not that hard to write a > script to go from a markup language to groff. I think the crux of the matter is going from a markup language *to a specific groff macroset*, not merely "to groff." A couple of years ago, Yves Cloutier and I discussed his idea of creating an entirely new markup language, which would begin life as a markup=>groff converter and proceed from there. Needless to say, he discovered quickly that his converter needed a macroset to map the markup to; conversion to low-level groff is futile because many of the operations groff is expected to perform demand being managed by macros. Going the reverse direction, groff=>markup language (e.g. HTML), it is equally evident that only conversions from a known macroset are going to produce semantically clean results. Thus, I feel that any work done on a grohtml-like device must start by determining an appropriate macroset to use for the conversion, then extending it to include additional macrosets. grohtml(1) makes no mention of macrosets, which lacuna can only be construed by users in one of two ways: grohtml is macro-agnostic, thus it will convert any macroset, or grohtml only converts low-level groff ("...converts the output of GNU troff to html."). I believe neither is true. Using -ms as an example, I would dearly love to see the DESCRIPTION in grohtml(1) begin: "The grohtml front end...translates the output of documents formatted with the groff_ms(1) macros to html. Users should always invoke grohtml via the groff command with the -Thtml and -ms options." -- Peter Schaffter http://www.schaffter.ca
Re: Releasing groff 1.22.5?
On Sat, Oct 10, 2020, Colin Watson wrote: > May I suggest bumping to 1.23? I know groff doesn't practise strict > semver, but this would be justified in that scheme (there are several > new features). I concur. Branden's Herculean labour of cleaning out the documentation stable alone merits a shiny new 1.23. -- Peter Schaffter https://www.schaffter.ca
Re: Learning troff - where to start?
On Wed, Oct 14, 2020, Damian McGuckin wrote: > How many people use features of 'groff' that are not in 'troff'? The mom macros rely heavily on extensions to groff that were implemented during Werner's term. Since many (most?) new groff users these days gravitate towards mom, I'd say quite a lot of people rely on those features. I learned troff entirely from ctsr54. It is not for nothing that it remains the canonical starting point for exploring groff. Prentice-Hall published _Troff Typesetting for UNIX Systems_ (Emerson, Paulsel) in 1987. It's still available online. It might be the very thing the OP is looking for. -- Peter Schaffter https://www.schaffter.ca
Re: Learning troff - where to start?
On Wed, Oct 14, 2020, Johann Höchtl wrote: > Groff is certainly feature-rich, stable and polished with > great documentation. But I also value l8n, being able to > input utf8-characters directly into the source or easily > switch fonts. Not to mention PAO (paragraph-at-once) from > Knuth-Plass. In that respect both Heirloom and Neatroff are > compelling alternatives and it would be great for mom if she would > be available there too. I haven't inspected either Heirloom or Neatroff closely so I don't know how big a job porting would be. I'm not likely to undertake it myself, though if anyone wanted to, I'd be more than happy to act as a go-to resource. What difficulties do you have entering UTF8 directly into the source? I've produced groff documents in most of the Western European and Scandinavian languages with direct UTF8 input. Are your troubles with languages other than those? Also not sure what you mean by "easily switch fonts." Since '.ft " is as easy as it gets, I assume you mean something else. -- Peter Schaffter https://www.schaffter.ca
Re: [bug #59573] typesetting.mom: traps are not initialised (set, planted)
On Sun, Dec 06, 2020, G. Branden Robinson wrote: > [redirecting to groff@ for discussion] > > Background: In https://savannah.gnu.org/bugs/index.php?59573, Bjarni > pointed out that a recent change I made caused some diagnostics to > appear. > > troff: ../contrib/mom/examples/typesetting.mom:638: error: cannot move > > unplanted trap macro 'FN_OVERFLOW_TRAP' > As noted in my commit message, I thought--admittedly based on > little but my own instincts and meager experience as a *roff > author compared to you--that it would be more helpful to aler the > user when they were doing something that "looked like" it should > do some work, but didn't really. What approach best suits the > user base? > > 1. Revert the change, possibly telling users in the manual how > write their own validity-testing wrapper for .ch. What would such a wrapper look like? I am unaware of how to test for whether a trap has been set other than .ptr, which prints to stderr. I'm in favour of reverting the change until we come to a consensus about its usefulness and how it's implemented. > 2. Postpone the change for after the 1.23.0 release but advise > of it in the release notes as planned subsequently, so people > have time to adapt. Not fond of this one. > 3. Downgrade the error to a warning. This seems reasonable, given the current nop behaviour, which groffers expect. It is useful for debugging to know a trap hasn't been planted, but, like an undefined string, it should be treated as a warning. > This will require determine an appropriate warning category for > it. I'd recommend mac (.warn 512), and update the description of mac in troff(1) and elsewhere to "Use of undefined strings, macros, diversions, and traps." My reasoning is that .ch "uses" a trap, hence the absence of that trap means you're using something undefined. A warning alerts you to a potential problem and allows you to do something about it if necessary; an error is just plain wrong and has to be fixed. The .ch problem is of the first category and should be treated as such. -- Peter Schaffter https://www.schaffter.ca
Re: [bug #59573] typesetting.mom: traps are not initialised (set, planted)
On Sun, Dec 06, 2020, G. Branden Robinson wrote: > Hi Peter! > > Thanks for the swift follow-up! > > At 2020-12-05T13:35:09-0500, Peter Schaffter wrote: > > On Sun, Dec 06, 2020, G. Branden Robinson wrote: > > > 1. Revert the change, possibly telling users in the manual how > > > write their own validity-testing wrapper for .ch. > > > > What would such a wrapper look like? I am unaware of how to test > > for whether a trap has been set other than .ptr, which prints to > > stderr. > > I don't think there is. I didn't think so, but if there's one thing I've learned about groff, it's that the list knows collectively what an individual may not. :) > > I'd recommend mac (.warn 512), and update the description of mac > > in troff(1) and elsewhere to "Use of undefined strings, macros, > > diversions, and traps." My reasoning is that .ch "uses" a trap, > > hence the absence of that trap means you're using something > > undefined. > > I like this, and would be happy to implement it. I don't know if my > scruples will permit to add simply "and traps" to the description like > that, though experts will surely "know what is meant", but I think I > interpret your intentions. You do indeed. "...and traps" was off-the-cuff. > I either lacked imagination when implementing > e3b909eda11419daaf9e1ff028defc0e972ac827 or underestimated your > creativity in exercising dark corners of the *roff language design > space. :) -- Peter Schaffter https://www.schaffter.ca
Re: preconv generates a good unicode escape but groff can't find special character
On Sun, Dec 06, 2020, Filip Banák wrote: > Hi. > > First of all, I swear it worked this morning. Then suddenly I process my > .mom file and the 'č' character is gone. > > This is the command and output: > preconv file.mom | pdfmom > file.pdf > troff: tema.mom:11: warning: can't find special character 'u0063_030C' I can't reproduce this. FreeSans in a test file spits out the 'č' character as expected. Can you attach a small file exhibiting the problem? -- Peter Schaffter https://www.schaffter.ca
Re: Fwd: preconv generates a good unicode escape but groff can't find special character
On Sun, Dec 06, 2020, Filip Banák wrote: > Okay, I absolutely do not understand this, but fail.mom is the fail that > shows the error. Yet now when I created a new file, test.mom, it works > flawlessly. There's a mistake in fail.mom, easy to miss. I didn't register it right away. AUTOLEAD 2 \# .LS 16 or .PT_SIZE + 2 The comment should be introduced by \" and not by \#. In the file test.mom you omitted the comment so everything processes correctly. -- Peter Schaffter https://www.schaffter.ca
Re: preconv generates a good unicode escape but groff can't find special character
> My personal opinion is that using syntax highlighting is a bad > idea in general... Of course, i'm aware that a majority of people > disagrees with this personal opinion and like syntax highlighting > for reasons i do not fully understand. Contrast and legibility. Grouping conceptually similiar items by colour assists mightily in wading through long swaths of code, and in a document using markup, distinguishes the text from the formatting. Html without syntax hightlighting? No way! It has, however, never occured to me that people use syntax highlighting for final syntax validation. I'd never condone that. Mind you, long patches of code/text in the wrong colour has alerted me to errors more times than I can count. > If you choose to use syntax highlighting, always assume that > the highlighting is totally bogus and makes no sense whatsoever. Methinks that's a little overstated. "Totally bogus" and "make no sense whatsoever" are erroneous assumptions since competent syntax highlighting is correct in more cases than it is not and generally makes perfect sense. Better to say "assume that the highlighting isn't perfect," which is both more accurate and a more useful piece of advice. > Never, ever rely on syntax highlighting for any kind of syntax > validation. "Never, ever rely on syntax highlighting for *final* syntax validation." -- Peter Schaffter https://www.schaffter.ca
Re: "mom": text on second page is overstruck
Steve -- On Sat, Dec 19, 2020, Steve Ross via wrote: > At the request of Oliver Corff, I've attached two files: > "test-macro-document-1.mom": The source file for "mom". (Please excuse the > random tests that fill the file.) I'm not seeing the attachments. Could you resend? -- Peter Schaffter https://www.schaffter.ca
Re: "mom": text on second page is overstruck
On Fri, Dec 18, 2020, Steve Ross via wrote: > The "groff" version is 1.22.3.The "mom" version is 2.1-c_1.The command line > is: $ groff -mom -Tpdf myText.mom > tmp.pdf Your document builds fine with the most recent version of mom (2.4-4_c). https://www.schaffter.ca/mom/mom-2.4-4_c.tar.gz -- Peter Schaffter https://www.schaffter.ca
Re: End-of-sentence spacing
On Sat, Dec 19, 2020, Ulrich Lauther wrote: > On Sat, Dec 19, 2020 at 10:27:01AM +, Dorai Sitaram wrote: > > groff pretty much forces one to use two spaces after > > sentence-ending punctuation, unless it's at the end of a source > > line. > > In my opinion it is good style to start every sentence on a new > source line. A piece of advice I have been happily ignoring since sometime back in the 90s. Certain kinds of texts (scientific, technical) and the ways they are to be used (e.g. one off, or formatted for multiple media types and platforms) undeniably benefit from it. But I simply cannot compose a work of fiction, or an article, or a rewiew one screen line at a time. It is not how one reads (at least not those of us who grew up reading ink on dead trees), and significantly interferes with one's ability to assess the meaning and flow of the text. This is the the first paragraph of _Bleak House_ typed one screen line at a time, no wrap: London. Michaelmas term lately over, and the Lord Chancellor sitting in Lincoln's Inn Hall. Implacable November weather. As much mud in the streets as if the waters had but newly retired from the face of the earth, and it would not be wonderful to meet a Megalosaurus, forty feet long or so, waddling like an elephantine lizard up Holborn Hill. Smoke lowering down from chimney-pots, making a soft black drizzle, with flakes of soot in it as big as full-grown snowflakes—gone into mourning, one might imagine, for the death of the sun. Dogs, undistinguishable in mire. Horses, scarcely better; splashed to their very blinkers. Foot passengers, jostling one another's umbrellas in a general infection of ill temper, and losing their foot-hold at street-corners, where tens of thousands of other foot passengers have been slipping and sliding since the day broke (if this day ever broke), adding new deposits to the crust upon crust of mud, sticking at those points tenaciously to the pavement, and accumulating at compound interest. I can't even read the whole text because half of it is off-screen! Moreover, if I turn wrapping on, the last sentence alone takes up six lines on an 80-col terminal and would be hell to edit for those of us who use 'k' and 'j' to navigate up and down in vi since a single 'j' moves the cursor six lines down--generally not what you expect. Wrap conflates 'k' and 'j' with '('and ')'. In other words, 'k' and 'j' effectively become sentence navigation commands instead of screen movement commands. This represents a significant loss of editing functionality. Here's the same paragraph, 72 characters per line, automatic wrap. "London. Michaelmas term lately over, and the Lord Chancellor sitting in Lincoln's Inn Hall. Implacable November weather. As much mud in the streets as if the waters had but newly retired from the face of the earth, and it would not be wonderful to meet a Megalosaurus, forty feet long or so, waddling like an elephantine lizard up Holborn Hill. Smoke lowering down from chimney-pots, making a soft black drizzle, with flakes of soot in it as big as full-grown snowflakes—gone into mourning, one might imagine, for the death of the sun. Dogs, undistinguishable in mire. Horses, scarcely better; splashed to their very blinkers. Foot passengers, jostling one another's umbrellas in a general infection of ill temper, and losing their foot-hold at street-corners, where tens of thousands of other foot passengers have been slipping and sliding since the day broke (if this day ever broke), adding new deposits to the crust upon crust of mud, sticking at those points tenaciously to the pavement, and accumulating at compound interest." I can see all the text, my head doesn't have to swivel like at a tennis match to read from left to right, and I can grasp the overall effectiveness of the paragraph in a few seconds. I can, furthermore, navigate up and down in the text in the expected manner in addition to jumping from sentence to sentence if I wish. Since groff imposes no requirement that each sentence be a unique source line, I see no reason even to suggest it to (new) users as good style, except as a useful, and perhaps at times required, strategy for collaborative/multiplatfom/multimedia documents. Furthermore, since groff treats end of sentence characters followed by one space, two spaces, or newlines identically when sentence spacing is disabled (as it is by default), the issue of whether to enter monospaced input with one or two spaces between sentences is moot. Either can be used. I prefer two because even in proportional font typesetting, readability is improved by the space between sentences being fractionally larger than the space between words; two spaces is how you tell groff to use sentence spacing when you're not doing
Re: End-of-sentence spacing
On Sat, Dec 19, 2020, Dave Kemper wrote: > I think you're confusing starting every sentence on its own line with > using newlines nowhere *except* between sentences. You are right. My distaste for hitting return instead of space after a period clouded my reading of the advice. :) > > Furthermore, since groff treats end of sentence characters followed > > by one space, two spaces, or newlines identically when sentence > > spacing is disabled (as it is by default), > > That *should* be true, but isn't > (http://savannah.gnu.org/bugs/?58500). Some non-English-language tmac > files disable wider sentence spacing, and perhaps some macro packages, > but by default groff itself does not. Perhaps I should have been more verbose and written: According to the info(1) manual, initially both the WORD_SPACE_SIZE and SENTENCE_SPACE_SIZE are 12; since this prevents SS from being larger than WS, it effectively disables sentence spacing. It just seemed easier to write "disabled by default." -- Peter Schaffter https://www.schaffter.ca
Re: End-of-sentence spacing
On Sun, Dec 20, 2020, Dorai Sitaram via wrote: > I'm not completely sure it's true for all modern applications, > but I hope you're right that it doesn't hurt in general to > explicitly type two spaces after a sentence. As a dinosaur, > that's what I used to do, but trained myself out of it after > reading a high-profile tirade scolding me (at least it felt like > I was being individually targeted, so I promptly wilted). I mean > of course the famous > > https://slate.com/technology/2011/01/two-spaces-after-a-period-why-you-should-never-ever-do-it.html The article addresses itself to the use of two spaces after a sentence *in typeset copy*, i.e. copy that uses proportional fonts, which is indeed frowned upon. How one enters monospaced text at the screen or on a typewriter--yes, people still use typewriters and the ribbon is still sold--is not covered at all, except to point out an error that results from conflating the two (putting two spaces in typeset copy). In typewriter-style copy, e.g. email, "two spaces between sentences" has been considered standard for a really long time. In my experience, it does make monospaced text easier to digest. I reflexively reformat received emails to introduce the extra space if it's not there. YMMV. That said, there is no reason not to introduce a tiny amount of extra space between sentences in typeset copy. It depends on the font. Those with tall caps in relation to the x-height usually don't need it, but those with caps that blend into the overall grey are often improved. It's a judgment call that requires a practised eye. -- Peter Schaffter https://www.schaffter.ca
Re: "mom": addition of ellipsis causes an over-strike
On Sun, Dec 20, 2020, Steve Ross via wrote: > In the resulting PDF output file, the ellipsis appears on page 10, > as expected. However, on the same line, about six characters > further to the right, I also see about three characters being > over-struck, which is unexpected. > > I have attached both the input "mom" file > ("sample_docs-steve.mom"), and the output PDF file > ("sample_docs-steve.pdf"). > > The "groff" version is 1.22.3.The "mom" version is 2.4-4_c. There is no overstriking when your file is processed with groff 1.22.4 (and later). From the age of your originally-installed mom and groff, it looks as if your distro hasn't kept up with groff development. -- Peter Schaffter https://www.schaffter.ca
Re: End-of-sentence spacing
On Tue, Dec 22, 2020, Tadziu Hoffmann wrote: > For those who have not read it yet: the original > > http://www.heracliteanriver.com/?p=324 > > has unfortunately vanished, but I have saved a copy: > > http://www.usm.uni-muenchen.de/~hoffmann/roff/tmp/typographyspacing.pdf Thank you! I hadn't read it, and I loved it. Basically, everything that was passed on to me when I apprenticed as a typesetter in a commercial shop lo, these many years ago: paragraph text benefits from sentences with a little more space between them than between words (the full em was considered a bit too old school). The amount of space was related to font, size, leading, and line length. When we switched to phototypesetting on Compugraphic 8400s (anybody remember those beautiful beasts?), we used the search/replace function to add "kern units" to spaces after EOS characters to achieve the effect. We'd do it in one pass, then give the galleys to the proofreader to catch the sentences beginning with capital T, V, W, or Y, which either needed no extra space or had to be brought back a tad. (There's something single-spacers never seem worried about, despite the obvious holes: tightening period-space-T/V/W/Y combinations. They could at least be consistent in their hatred of unequal word/sentence spacing!) -- Peter Schaffter https://www.schaffter.ca
Re: End-of-sentence spacing
On Tue, Dec 22, 2020, Dave Kemper wrote: > It seemed a minor thing before, but now that it's tripped up the > author of possibly the most elaborate macro package published in > the roff language's 50-year history, I wonder if that's worth > revisiting. Being said author, I can confirm that yes, I did indeed get tripped up in exactly the way Dave described: quick check of paragraph one to refresh my memory, not reading under the fold, forgetting that sentence space means additional space. I obviously knew once or mom wouldn't have macros for manipulating word and sentence spacing, but it's something I haven't had to think about in years. That said, while the info entry for .ss is accurate as is, the material does need to be re-ordered somewhat. First off, a reader of the entry, looking for information on sentence spacing, and rationally assuming 'ss' stands for 'sentence space,' is presented, surprisingly, with "Change the size of a space between *words.*" Then, because of the capitalization of the argument descriptions, the eye tends to jump to: "Initially both the WORD_SPACE_SIZE and SENTENCE_SPACE_SIZE are 12," which, without some explanation of sentence space, leads to the conclusion that the value of sentence_space_size is discrete. The erroneous conclusion then appears to be confirmed in the second paragraph: "If the second argument is not given, sentence space size is set to WORD_SPACE_SIZE," which, as before, suggests "is equal to," not "is added to", word space size. So, yes, it's worth re-working the info .ss entry. Perhaps begin with something like: "Change the size of the space between words and sentences. The space between sentences is derived by adding WORD_SPACE_SIZE and SENTENCE_SPACE_SIZE. Thus '.ss 12 0' results in no additional space being added between sentences, whereas '.ss 12 12' results in an additional 12 units of space between sentences." -- Peter Schaffter https://www.schaffter.ca
Re: End-of-sentence spacing
On Tue, Dec 22, 2020, John Gardner wrote: > I condemn two spaces, period. Having gotten bitten by the who-says-what-where bug concerning double-spaced sentences, I re-read my own documentation for the .SS macro in mom. Seems to me I covered all the bases: "Typeset copy should never have two spaces between sentences, and the "zero" argument [to .SS] tells groff to give the extra spaces no space at all (effectively removing them). Therefore, if you double-space your sentences (as you should when writing in a text editor), get in the habit of putting .SS 0 at the top of your files. If you do use SS for something other than ensuring that you don’t get unwanted sentence spaces in output copy, you can set or reset the sentence space to the groff default (the same width as a word space, ie double-spaced input sentences will appear double-spaced on output as well) with .SS DEFAULT If you’re using the document processing macros and your PRINTSTYLE is TYPEWRITE, .SS DEFAULT is the default, because you do want double spaces between sentences in copy that imitates the look of a typewritten document." -- Peter Schaffter https://www.schaffter.ca
Re: Sample thesis template for groff mom
Shane -- On Wed, Jan 20, 2021, Shane Bishop wrote: > I'm a university student working on my thesis for my Honours > Bachelor of Computer Science. I'm new to groff, and I'm wondering > if there is a place where I can access sample templates/groff > source for University theses. > > I'm looking for examples using the mom groff macros, but if there > are samples in another macro set, that might be valuable as well. There are no templates of the sort you're looking for. > I took a look in /usr/share/doc/groff/examples/mom, which did have > some useful examples, but it didn't have an example for formatting > captions on embedded images, or an example with a bibliography. Examples of these are in the html documentation, rather than in example files. Have a look there. The online documentation is at https://www.schaffter.ca/mom/momdoc/toc.html -- Peter Schaffter https://www.schaffter.ca
Re: source code of groff-and-mom.pdf
On Sat, Jan 30, 2021, Senor.Pan.Tau--- via wrote: > Hello, > does anyone have the source code of the pdf manual groff-and-mom.pdf > available for study purpose? To many non experts it is easier to anderstand > via examples instead of theory. > It wouldn't have to be the complete code of course, but may-be somthing like > the first and last 10 pages or so. > Thanks a lot, > PanTau Copy of source code sent off list. -- Peter Schaffter https://www.schaffter.ca
Re: Formatting bibliography with mom and refer
On Tue, Feb 02, 2021, - - wrote: > I'm not quite sure what's decided by refer and what by mom > regarding the format of the references in my bibliography list. The formatting of references is controlled by mom (order of fields, punctuation, italics). > I currently have no idea how to affect the order of the fields. ... > Is there anyway to include the field/change the reference label > format in general with macros or do I need to dive into the tmac > files? Mom generates references in MLA style, which is hardcoded into mom's macro file, om.tmac. Making changes requires making changes in that file. The order of fields is set in the 'ref*specs' macro; punctuation and spacing are determined by the various 'ref*add-' macros, where is the single-letter field identifier. If you're new to groff, you'll like find mucking about in om.tmac a bit intimidating, the 'refer' section particularly, however the code is well commented. Ask if you have any questions whatsoever. > I have a reference database file containing mainly web site > references but the site URL inserted to %u field is not shown in > the output document in anyway and that's a big problem for me. I imagine the missing %u is because you're using an old version of mom, most likely the one that shipped with your groff installation. The %u bug was reported and fixed a while ago. Grab a copy of the most recent version of mom from https://www.schaffter.ca/mom/mom-2.4-4_e.tar.gz and replace your version of om.tmac with the one in the package. Again, if you have questions, ask. -- Peter Schaffter https://www.schaffter.ca
Re: Long text in tbl won't wrap, maybe related to mom
On Fri, Feb 05, 2021, Bento Borges Schirmer wrote: > I'm having great joy composing little documents for some homework > and assignments using groff and the mom package. Yesterday I > wanted to learn how to make tables so I read through mom's > excellent documentation and reproduced all tables except the last > one from L. L. Cherry and M. E. Lesk's Tbl --A Program to Format > Tables, when I encountered a problem where the lines wouldn't > wrap: The problem is twofold. The first is that your example doesn't appear to be formatted correctly with respect to tabs. Your email shows spaces. I don't know if that's something that happened with my mail client or whether you genuinely used spaces. At any rate, it's always a good idea with tbl(1) to specify the tab character so it's visible. Most folks use tab(@) in their global options. The other source of your problem is indeed in mom. Tbl appears to require that adjusting be turned off in order to process text blocks correctly, which mom is not presently doing. If you precede calls to '.TS' with '.na', and follow calls to '.TE' with '.ad', tables process as expected. The following, copied directly from Lesk with the addition of @ as the tab delimiter, produces the table as expected (with mom-2.4-4_e and 'pdfmom -t file.mom > file.pdf') .PRINTSTYLE TYPESET .START .na .TS expand tab(@); cb s s s c | c | cs ltiw(1i) | ltw(2i) | lp8 | lw(1.5i)p8. Some Interesting Places _ Name@Description@Practical Information _ T{ American Museum of Natural History T}@T{ The collections fill 11.5 acres (Michelin) or 25 acres (MTA) of exhibition halls on four floors. There is a full-sized replica of a blue whale and the world's largest star sapphire (stolen in 1964). T}@Hours@10-5, ex. Sun 11-5, Wed. to 9 \^@\^@Location@T{ Central Park West & 79th St. T} \^@\^@Admission@Donation: $1.00 asked \^@\^@Subway@AA to 81st St. \^@\^@Telephone@212-873-4225 .TE .ad I will make the necessary change to om.tmac and commit it as bugfix release (2.4-4_f) in the next day or two. The change will also be present in the 'current release' tarball on mom's website. Meantime, just manually add the .na/.ad. -- Peter Schaffter https://www.schaffter.ca
Re: First post...
On Sun, Feb 07, 2021, tu...@posteo.de wrote: > Is this mailing list the right place to post genral questions about > "how to troff" or is this mailing for groff specific questions? I believe you will never find a group of people more knowledgeable about troff, going right back to its earliest implementation. Ask away! -- Peter Schaffter https://www.schaffter.ca
Re: Hierarchical numbering in mom
On Tue, Feb 09, 2021, Dmitriy Kurshakov wrote: > I am trying to make a document with hierarchical numbering like in > agreement: > 1. Heading 1. > 1.1. Long paragraph 1.1. > 1.2. Long paragraph 1.2. > 2. Heading 2. > 2.1. Long paragraph 2.1. > ...and so on. > As far as I understand mom's documentation, the hierarchical numbering is > available only for headings. True. > My attempts to get hierarchical paragraph numbering with nested > lists has no success. LIST is not the way to go. Rather, put this at the top of your file: .am HEADING . nr para 0 1 . nr head +1 .. .am PP \\n[head].\\n+[para].\ \" .. Assuming '.HEADING_STYLE 1 NUMBER', normal usage of .HEADING 1 .PP .PP will give you paragraphs numbered as per your example. Note that this is a quick and dirty solution. It works correctly only for first-level headings. -- Peter Schaffter https://www.schaffter.ca
Re: groff: FLOAT FORCE and PDF_IMAGE with mom macros
Shane -- On Thu, Feb 11, 2021, Shane Bishop wrote: > I am trying to create a PDF document with the mom macros using the > PDF_IMAGE macro. I want my images to automatically move to the > next page when there is insufficient vertical space for them on > the current page. >From the docs: "Mom now treats all pdf images identically to floats, which is to say that if an image doesn’t fit on the output page, she will defer it to the top of the next page while continuing to process running text." However, if you want text to stop at the place the pdf image is inserted in the source file, leaving a hole at the bottom of the page, then FLOAT FORCE is the way to go. > When I compile my PDF with the command > pdfmom -t report.mom > report.pdf, > I get an "environment stack overflow". The PDF generates just > fine, despite the warning. I'm not seeing the warning at my end. Which version of mom are you using? pdfmom -dVERSION=1 foo will tell you. (Foo can be anything; pdfmom just needs a name of some sort or it will hang.) The current version is 2.4-4_e. If you are up-to-date, could you send a file (and its associated images) exhibiting the warning? I dealt with it in version 2.2, or so I thought. -- Peter Schaffter https://www.schaffter.ca
Re: groff "mom": How to add vertical space around bullet items?
On Mon, Feb 15, 2021, Steve Ross via wrote: > I may have missed it in the "mom" documentation, but I'm looking > for a way to adjust the vertical spacing between the ITEMs of a > LIST. Use ITEM (e.g. ITEM .5v to put half a linespace between list items). If you always want the same spacing, redefine ITEM to include it, like this: .rn ITEM ITEM-orig .de ITEM . ITEM-orig .5v .. Spacing above and beneath LISTs must be entered explicitly with a spacing macro or request (.SP, .ALD, .sp). Mom makes no assumptions concerning list spacing, given the multitude of uses and abuses to which LIST/ITEM are routinely subjected. -- Peter Schaffter https://www.schaffter.ca
Mangled pdf in Chrome browser?
A user contacted me off list saying that the example pdf file at https://www.schaffter.ca/mom/pdf/sample-formatted-article.pdf is rendering as garbage in the Chrome browser. I don't use Chrome. Can someone check if this is true? -- Peter Schaffter https://www.schaffter.ca
Re: Mangled pdf in Chrome browser?
On Sat, Feb 20, 2021, Andreas Kusalananda Kähäri wrote: > On Sat, Feb 20, 2021 at 11:42:09AM -0500, Peter Schaffter wrote: > > A user contacted me off list saying that the example pdf file at > > > > https://www.schaffter.ca/mom/pdf/sample-formatted-article.pdf > > > > is rendering as garbage in the Chrome browser. I don't use Chrome. > > Can someone check if this is true? > > Renders ok to me. Does the user know that most of the text is supposed > to *read* as "garbage", i.e. the classic placeholder "Lorem ipsum" text? > Are they expecting a real text? He says everything is garbled, mangled fonts, weird paragraphs, etc, so no, he's not mistaking greeking for unintentional gibberish. I've suggested, given that this would be a pdf issue and not in my bailiwick, that he contact the list with details if the problem persists. -- Peter Schaffter https://www.schaffter.ca
Re: Mangled pdf in Chrome browser?
On Sat, Feb 20, 2021, Robert Goulding wrote: > It looks fine to me on Chrome 88.0.4324.186 (on a Chromebook) - R. Thanks for checking. -- Peter Schaffter https://www.schaffter.ca
Update groff_tmac(5)
I don't look at groff_tmac very often. I just noticed this entry for the mom macro package: mom The new mom macro package, only available in groff. As this is not based on other packages, it can be freely designed. So it is expected to become quite a nice, modern macro package. See groff_mom(7). Mom's been around for almost two decades. She's no longer the new kid on the block. Isn't it time this entry be updated? -- Peter Schaffter https://www.schaffter.ca
Soft hyphens
When hyphenation is disabled, soft (discretionary) hyphens are interpreted. I discovered this when a mom user emailed me that (some) soft hyphens were appearing as hard hyphens between syllables mid-line when run-on, line-numbered footnotes were being output, even though hyphenation was disabled in the environment in which the footntes were collected. The solution to the problem was to disable filling, not hyphenation. I'm wondering if the interpretation of soft hyphens when .nh is active is correct behaviour. It's counter-intuitive and feels like a bug. If it is the expected behaviour, we need to amend the info manual to state that .nh does not disable the interpretation of soft hyphens. -- Peter Schaffter https://www.schaffter.ca
Re: Soft hyphens
On Sat, Apr 03, 2021, Dave Kemper wrote: > On 3/28/21, Peter Schaffter wrote: > > I'm wondering if the interpretation of soft hyphens when .nh is > > active is correct behaviour. > > I don't know the answer to your question, I got an answer from Doug McIlroy. "In pre-Unix roff hyphenation mode 0 turned off all breaking of words. The original troff, however, behaved as described above, and also broke genuinely hyphenated words in mode 0." > but in general, anything that will require some kind of change > --even if it's presently unknown whether that change is to the > software or to the documentation--should have a savannah ticket > opened (http://savannah.gnu.org/bugs/?group=groff&func=additem) to > keep tabs on it. >From what Doug said, I don't think it qualifies as a bug, more of an idiosyncracy. I do think it needs to be documented in the info manual, though. I've opened a ticket and assigned it to Branden. -- Peter Schaffter https://www.schaffter.ca
Re: Update groff_tmac(5)
On Sat, Apr 03, 2021, Dave Kemper wrote: > On 3/28/21, Peter Schaffter wrote: > > Mom's been around for almost two decades. She's no longer the new > > kid on the block. Isn't it time this entry be updated? > > This was updated a few weeks ago in commit bbbcafc8 > (http://git.savannah.gnu.org/cgit/groff.git/commit/?id=bbbcafc8). > The description of mom could still be refined if you have a > wording you'd prefer. I missed that commit. Thanks for drawing it to my attention. The wording is fine. -- Peter Schaffter https://www.schaffter.ca
Re: Soft hyphens
On Sun, Apr 04, 2021, G. Branden Robinson wrote: > I think the sentence > >Explicitly hyphenated words such as "mother-in-law" are eligible for >breaking after each of their hyphens when GNU 'troff' fills lines. > > does most of the work you're asking for... It does, but for clarity and and completeness, the sentence must mention soft hyphens. A word with a soft hyphen cannot be said to be "explicitly hyphenated"; the nature of a soft hyphen is that it's optional, not explicit. Even if it can be argued that a soft hyphen is explicit because it's introduced by the user, the potential for misunderstanding warrants clarification. Something like Explicitly hyphenated words such as "mother-in-law" or "brother\%hood" are eligible for breaking after each of their hyphens... or Explicitly hyphenated words such as "mother-in-law" and words containing the soft hyphen character are eligible for breaking after each of their hyphens... would be more useful than requiring readers to extrapolate (a Very Bad Thing in documentation) that the discretionary hyphen counts as an explicit hyphen. Equally, the corresponding entry for .nh needs to include that explicit and soft hyphens continue to be interpreted as valid break points. Conceptually, soft hyphens feel like part of automatic hyphenation, even if groff doesn't treat them as such. Users need to be alerted in order to prevent surprises. -- Peter Schaffter https://www.schaffter.ca
Re: "point size" is not usable as a term
On Mon, Apr 19, 2021, Bjarni Ingi Gislason wrote: > Bug #60403 (closed) unified the writing of "point-size" to "point > size". > > The problem is, > that this coinage does not make sense. > > The "point" in this compound, > is a name of a unit of measurement, > is thus a constant, > but its definition > (size, numerical value) > depends of the used measurement system > (system of units). > > The right term is "type size", > which is usually measured (stated) in "typographic points". And then there's the real world, where 'point size' is used by every (English speaking) typesetter, graphic designer, and proofreader I've ever worked with. Like it or not, 'point size' became synonymous with 'type size' a very long time ago. The groff manual is not a place for grinding semantic axes. Use of the near-universal 'point size' is preferable. -- Peter Schaffter https://www.schaffter.ca
Re: mom: install-font.sh
On Thu, Apr 29, 2021, Wim Stockman wrote: > I found a small bug in the wonderful install-font.sh script on > your mom website in the make_font function you should add the > "-e text.enc" to the afmtodit_opts Done. Thanks. -- Peter Schaffter https://www.schaffter.ca
Re: man-intro
On Sun, May 23, 2021, Oliver Corff wrote: > in a follow-up to my last message I just want to give one > real-world example of a very terse manpage, "for the initiated > reader only." > > Take refer(1). > Terseness is nice, but in the case presented here the first paragraph of > DESCRIPTION in the refer(1) manpage is logically true, though not truly > helpful. In support of Oliver's feelings on the subject, I cite from the mom documentation, written years ago: "Refer has been around for a long time. It's powerful and has many, many features. Unfortunately, the manpage (man refer), while complete and accurate, is dense and not a good introduction. (It's a classic manpage Catch-22: the manpage is useful only after you know how to use the program.)" (Pedants: I use Catch-22 in its popular meaning, not the strict Hellerian definition.) > Sometimes a minimal degree of verbosity makes everything clearer. Hear, hear. I had a German prof at UofT years ago who was fond of saying: Never use one word where two will do. Ironic, given the source, but he was talking about English style, not German. I confessed to Branden off list recently that the origins of the mom macro set are to be found in my intense frustration with the terse, nearly opaque documentation of all things *roff. (Exception made for cstr54, which somehow balances conciseness with readability.) My feeling was that if I could translate groff's machine-code documentation to something humanly readable, it would attract users. That morphed into "Why not write a complete user interface for groff and document it separately, sparing users from having to read *roff documentation at all?" Years later, I realise I bit off far more than I expected to chew, but the idea was sound. Mom and her documentation have drawn a lot of new groff users. -- Peter Schaffter https://www.schaffter.ca
Re: Macro's for making an exam.
On Wed, Jun 09, 2021, Hans Bezemer wrote: > .if (\n[s] == 0) .ig ++ > .br > Text > .++ > > But when I try to put it in a macro it doesn't work: > .nr s 0 > .de SOLUTION > .if (\n[s] == 0) .ig ++ > .br > .. > .de SOLEND > .++ > .. You need to escape the backslash when it's in a macro definition: .if \\n[s]=0 .ig ++ Alternatively, disable the escape mechanism: .eo .if \n[s]=0 .ig ++ .ec -- Peter Schaffter https://www.schaffter.ca
Re: [mom] Using LIST with DOCTYPE SLIDES
On Sun, Jun 13, 2021, Oliver Corff wrote: > With regard to .PRINTSTYLE, the mom manual online is quite > assertive, but for the example here it did not seem to produce any > differences in output, either present or absent. Erm... momdoc/docprocessing.html#slides: "PDF slides are a special kind of mom document, formatted for viewing in a PDF reader’s presentation mode. In most respects, they behave identically to the other document types. Key differences are: - headers, footers, and pagination are disabled by default - type is set QUAD CENTER by default - flex-spacing and shimming are disabled by default; shimming may be re-enabled (with NO_SHIM OFF), but not flex-spacing - there’s no need for PRINTSTYLE" ^^ For all other doctypes, yes, definitely assertive. :) The rational for slides not requiring PRINTSTYLE is that since no one is going to need typewritten, double-spaced, MLA-formatted slides, the template is always TYPESET. -- Peter Schaffter https://www.schaffter.ca
Re: [mom] Using LIST with DOCTYPE SLIDES
On Mon, Jun 14, 2021, Oliver Corff wrote: > Let's say, "to need anymore". In the early 1990s, I was once tasked with > making presentation slides, and since video projectors were not readily > available, real slides were the way to go. Text presentations were > delivered to a terminal of which I took pictures with Polaroid 135 film > (rapid development within minutes with dedicated processor), the film > was then cut and framed and the presentation was ready to go. Blast from the past! Makes me nostalgic for the days of galley type from huge rolls of photograpic paper, cut up and assembled on artboards (rules and whatnot drawn by hand with a Rapidograph), and handed off to the camera department for negatives, Dylux proofs, and final plates. Pre-press was a lot more fun before DTP. -- Peter Schaffter https://www.schaffter.ca
Re: "absolute" vertical position seems awfully relative
On Mon, Jun 21, 2021, Dave Kemper wrote: > But specify a macro package of -ms, -me, or -mm on the command line, > and the results change: the text is now in noticeably different > positions on the two pages. The placement with all three macro > packages is remarkably similar. > > Why should a macro package change groff's concept of an absolute > distance from the top of a page? The mom macros don't exhibit the behaviour. I wouldn't have thought it possible. The question isn't why should it, but how could it? The only thing I can think of is that the .bp is triggering a macro that changes the .vs. That could result in different vertical placements, but not, I think, "noticeable." -- Peter Schaffter https://www.schaffter.ca
Re: Introducing mu, my new macro package
On Thu, Jul 01, 2021, John Ankarström wrote: > I've been working on my own troff macro package for the last couple of > weeks, and I thought I'd share it with you here: As Mike said, welcome to the Macro Writers Guild. :) -- Peter Schaffter https://www.schaffter.ca
Re: Question about ?roff on Reddit
On Wed, Jul 14, 2021, Nate Bargmann wrote: > I saw the following post on r/linux today: > > https://www.reddit.com/r/linux/comments/ojkjm9/how_do_nrgroff_compare_with_more_modern_text/?utm_source=share&utm_medium=web2x&context=3 > > Perhaps some of the folks here can provide some insight. I have no desire to create a Reddit account just to answer this thread, but I hope someone else on the list does. It seems absurd that in 2021 people still have notions about groff that were already out-of-date twenty years ago. If someone does respond on Reddit, can said person please notify the list so the rest of us can read what's said? -- Peter Schaffter https://www.schaffter.ca
Re: Macros for printing envelopes?
Nate -- On Thu, Jul 15, 2021, Nate Bargmann wrote: > As I see it, with groff I can easily create files for addresses I > use often and should be able to code a script that accepts those > one-off addresses. I use this strategy with the mom macros. Here's the .mom template file: --envelope template--- .\" #10 envelope (US) .PAGE9.5i 4.125i .3i .3i .4i .4i .FAM Futura .FT R .PT_SIZE 11 .LS 13 .LEFT .\" Return address here .IL 3.5i .SP |2i-1v .PT_SIZE 12.5 .LS 15 .\" Destination address here The Return address is always filled in. In a script, the Destination address can either be cat(1)ted together with the template from an address on file, or groff's .rd request can be appended to the end of the template so one-off addresses can be typed in at the command line. Depending on your printer, you may need to rotate the file to landscape orientation (the -P-l flag at the command line). Hope this helps. -- Peter Schaffter https://www.schaffter.ca
Re: Macros for printing envelopes?
On Fri, Jul 16, 2021, James K. Lowden wrote: > On Fri, 16 Jul 2021 12:44:04 -0400 > Peter Schaffter wrote: > > > On Thu, Jul 15, 2021, Nate Bargmann wrote: > > > As I see it, with groff I can easily create files for addresses I > > > use often and should be able to code a script that accepts those > > > one-off addresses. > > > > I use this strategy with the mom macros. Here's the .mom template > > file: > > But ... don't you need some kind of input-tray selection escape, or > something? How does the printer know to pause and wait for you to > insert an envelope? Depends on the printer, I guess. My one-tray printer knows I've inserted envelopes because I insert them before processing/sending-to-printer. Very old school. :) The OP was wondering about how to set up envelopes using groff without having to write new macros. It's easy, as my example showed, and that's what I hoped to convey. FWIW, it doesn't require a macroset. It's a walk in the park to create an envelope template using just groff requests. How such a template is used with a script, however, is entirely site dependent. As far as selecting trays goes, that can be done with lpoptions(1) or the -o flag to lpr(1) in the script. -- Peter Schaffter https://www.schaffter.ca
Re: Fwd: Would it be reasonable to list the fonts that are available by default in groff?
Kurt, thanks for saving me having to explain why groff doesn't know anything about install-font.sh and fontforge. Doug, I hope you see this. On Sat, Jul 17, 2021, T. Kurt Bond wrote: > In the meantime, if you want to install fonts in OpenType or TrueType > formats for use with devps and devpdf, install-font.sh greatly simplifies > the process. > $(IFDIR)/install-font.sh -n -P "$DEST" -d -F CormorantGaramond -f +R > CormorantGaramond-Regular.ttf Which doesn't look very simplified at all. If I wanted to sing the simplicity of the script, the example command line would be: sudo install-font.sh Answer a few questions the script asks, and hey, presto! everything's taken care of. > ...but not all distributions create the site-font directory. The script creates it if it's not found in what are, honestly, the only two locations it's ever likely to be, and populates it with devps/ and devpdf/, which in turn are each adorned with dummy DOWNLOAD files. The script alerts you to what it's doing. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Mon, Aug 02, 2021, G. Branden Robinson wrote: > Why does refer(1) have no database field for "edition"? > > GNU refer doesn't. Neither did AT&T refer according to my searches. The lacuna isn't in refer(1), but in the macro packages using it. Any %c, where c is an alphabetic character, can be used to create a field refer(1) understands. It is up to macro writers to work out the the formatting and placement within a refer(1) citation or bibliography entry. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Mon, Aug 02, 2021, Oliver Corff wrote: > I also have a few more fields on my wish list, like for > translator, and subsequently, original title. In mom, the translator field identifier is '%l'. MLA style, which mom observes, has no rules for the inclusion of the original title of a translated work, presumably because if you're citing a translation, the name of the original is not significant for the purposes of research or verification, at least not in a list of Works Cited. MLA recommends that if you want to convey the original title of a translated work, the original name should appear in your prose. That said, it you don't want to follow MLA punctiliously, you could co-opt mom's '%t' identifier (original title of a work if the citation is from a reprint with a different title). Thus, %T would be the title of the translation, and %t would be the original title. %t would have to be slightly modified in om.tmac (the macro ref*add-t) because the prefix to %t includes "Rpt. of". It's an easy change to make. > Perhaps, but this is really just a wish, it would be great to > include a mechanism for a more flexible choice of bibliography > styles. Agreed, but it's a big job. Even working from refer.tmac (APA? Chicago?), it took weeks to set up MLA in mom and iron out the bugs. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Mon, Aug 02, 2021, Oliver Corff wrote: > Hello Peter, > > since you have demonstrated with mom how to extend the standard, if not > to say "frozen" capabilities of the macros for refer(1), and with regard > to the offline conversation we already had on the topic of bibliography > styles, what would be your verdict on the idea to isolate the > bibliography processing part (that is, understand %c fields and > formatting) and put everything into a macro package of its own, perhaps > with an interface to introducing more bibliography styles? From your > perspective as the creator of a full-fledged macro package, what are the > caveats? The only real issue would be establishing the most efficient way to make the different biblio styles available to the various macro packages. Without bothering to check (it's a holiday in Canada today and I intend not to work), piggy-backing on the existent refer-mm/ms/me.tmac and refer.tmac arrangement might do the trick. The one caveat is that bibliography style is intimately linked with citation style, so switching to a style different from a macro package's default might require changes within the package's tmac file as well. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Mon, Aug 02, 2021, Tadziu Hoffmann wrote: > > > > Why does refer(1) have no database field for "edition"? > > > The lacuna isn't in refer(1), but in the macro packages using it. > > Any %c, where c is an alphabetic character, can be used to create > > a field refer(1) understands. It is up to macro writers to work > > out the the formatting and placement within a refer(1) citation or > > bibliography entry. > > Certainly it can be extended, but it would be useful if > there were some general agreement on which character to use > (preferably something mnemonic; "E" is already taken by > "editor"), unless you are satisfied with a solution that > works only with one macro package (if competing approaches > are taken by the writers of different macro packages). Mom uses %e for edition. It's the best candidate since it has a twenty year history of being used in mom documents. No other package I know of claims it, meaning, in real terms, that its use is established (sort of). > Sticking it onto the end of the title field is ugly, because > one might like the title to be printed in italics, whereas the > edition is "meta information" and should therefore perhaps be > in the regular font. There are no should therefores or guesswork when it comes to formatting bibliographies. Where edition goes and how it's formatted is fixed by the style: *Chicago puts it after the title, preceded by a comma, in roman, followed by the publication data in parentheses. *APA places it in parentheses after the title, in roman, with a period after the right parens. *MLA puts it after the title, preceded by a period, in roman, followed by a comma, followed by the publication data. Those are the only ones I know, but you catch my drift. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Mon, Aug 02, 2021, Tadziu Hoffmann wrote: > > > There are no should therefores or guesswork when it comes to > > formatting bibliographies. Where edition goes and how it's > > formatted is fixed by the style: [...] > > If you're submitting a paper to a journal you obviously have to > follow the journal style (usually the editors will take care of > that), but for in-house documents I'm not required to use either > of those styles and can define my own, in which case I do have a > choice on how to format the bibliography. Indeed, but the subject under discussion is making refer(1) conformant to various acknowledged styles, not in-house usage. -- Peter Schaffter https://www.schaffter.ca
Re: Why does refer(1) have no database field for "edition"?
On Tue, Aug 03, 2021, Tadziu Hoffmann wrote: > > Indeed, but the subject under discussion is making refer(1) > > conformant to various acknowledged styles, not in-house usage. > > But isn't that the job of the macro package, not refer? Yes, it is. My phrasing, above, was poor. > I guess the question is "How can refer make that job easier?", > which you answered by saying that mom defines a new database > field for the edition. If we consider this usage the status > quo, should it be documented with an appropriate entry in the > list of field names in the refer manual page? Not unless (until?) it's implemented for all the canoncical macro packages. I proposed %e as a candidate for the edition field because it's been around long enough in mom that it makes sense for other macro packages to follow suit. Plus it has the advantage of being a meaningful mnenmonic. > (The manual page does speak of the "conventional meaning" of > each field, implying that this is by common agreement rather > than by rule of an authority.) That is indeed the case. Field identifiers for refer(1) are arbitrary. Two things surprise me about what I'll call "the whole refer picture." One is that ms/mm/me do not implement fields for URLs and other Web/Internet sources. Mom implements five additional fields for Internet sources as required by MLA: %s site name %c content (e.g. Web, Email, Blog...). %o organization, group, or sponsor or the site %a access date %u URL Methinks, in 2021, that the other groff macro packages should catch up with this newfangled Internet thingy. The other is that nowhere is there any indication what style of bibliographic formatting is provided by the ms/mm/me implementations of refer(1), a matter of some importance for authors preparing submissions and students writing papers. Mom is upfront about formatting in MLA style, which is useful to groffers seeking a macro package that does MLA. I believe the other packages should follow suit and state, in their manpage or in refer(1), which style guide is being followed for refer(1) bibliographies. -- Peter Schaffter https://www.schaffter.ca
Mom html docs
Branden -- On the groff-commit list I noticed two commits fixing typos in mom's html docs. Pleased you spotted them, of course, but... Because mom is a contrib project, I maintain the documentation myself. We might end up at cross-purposes with two sets of eyes going over it and committing changes. Better to send me patches or just draw things to my attention. Mom version releases always include doc fixes along with additions and emendations. That said, I sure woudn't mind your eagle eyes scouring the momdocs with the same zeal and aplomb with which you've been attacking the groff docs. If you're of a mind to continue, let me know and I'll hold off making a version release (in the works) until you're done committing changes. -- Peter Schaffter https://www.schaffter.ca
Re: Pushing a mom test fix
Branden -- On Tue, Oct 05, 2021, G. Branden Robinson wrote: > The number of pages in the slide demo has gone up from 27 to 33. ...while the number of slides in the file has only gone from 7 to 8. It's the number of PAUSEs that's increased. Useful to know. Something in the pipeline is tagging material after a PAUSE ('.pdfpause' from pdf.tmac) as a new page. -- Peter Schaffter https://www.schaffter.ca
Re: Pushing a mom test fix
>> Something in the pipeline is tagging material after a PAUSE >> ('.pdfpause' from pdf.tmac) as a new page. > > Each separate transition is in fact a "page" That's what I figured when I saw Branden's commit. Is this something that should be documented? I don't imagine many users need to know the number of virtual pages in a slide presentation. On the other hand, maintainers might, as Branden discovered. -- Peter Schaffter https://www.schaffter.ca
Absolute spacing redux
I've been frustrated by groff's absolute spacing (.sp |) for decades. First off, is calculated from the first baseline of the vertical spacing currently in effect when .sp | is called, not from the top edge of the printer medium or PDF/PostScript display. The behaviour is documented in the info manual and a workaround is provided, but that doesn't obviate that while for tty devices the behaviour makes sense, it doesn't for -Tps and -Tpdf, which, I posit, are more frequently used in 2021 than tty devices, manpages notwithstanding. Secondly, this behaviour has consequences beyond the annoyance of having to add -\n(.vu or -1 to absolute spacing requests. Consider: .ds A "Now is the time for all good men .ds B "to come to the aid of the party. . .\" First half .nf .ps 12 .vs 24 .sp |1i-1 \*A .ev foo .evc 0 .vs 18 .di bar \*B .di .ev .sp |1i-1 .in \w'\*A 'u .bar .in . .\" Second half .sp |2i-1 .mk \*A .ev foo .di baz \*B .di .ev .rt .in \w'\*A 'u .baz The first half uses '.sp |dist-1' before outputting its diversion, the second uses .mk/.rt. In both cases, processed with -Tpdf or -Tps, string B is higher than string A; diversions whose vertical spacing differs from the prevailing one are not output at the location arrived at by '.sp |dist-\n[.v]u' but rather '.sp |dist-\n[.v-at-top-of-diversion]u'. In a demonstration like this one, the problem is correctable by transparently embedding the .ev foo/.evc 0 requests in the first half inside its diversion, but in complex, trap-invoked macros this strategy may not be desirable or even possible. Alternative, context-sensitive solutions are often non-evident and fussy to implement. I believe groff needs a dedicated request for unambiguous absolute spacing. One that says, "Advance from the top of the printer sheet to the location I say and print whatever comes next right there." The same goes for .mk/.rt. (Preparing mom 2.5, I was surprised to discover that .rt suffers from the same problem, one of the reasons I've decided to bring this up.) What say ye? I'd like to put this in as feature request, but there's not much point if others don't see its utility. -- Peter Schaffter https://www.schaffter.ca
Re: Pushing a mom test fix
Branden -- On Thu, Oct 07, 2021, G. Branden Robinson wrote: > Hi, Peter! > > At 2021-10-05T15:37:09-0400, Peter Schaffter wrote: > > >> Something in the pipeline is tagging material after a PAUSE > > >> ('.pdfpause' from pdf.tmac) as a new page. > > > > > > Each separate transition is in fact a "page" > > > > We could add a notice in gropdf(1) about this. I don't think it's necessary. You more or less confirm that page counts of slide files are a non-issue outside of Bertrand's script. I'm sure if anyone needs to know that transitions count as pages, the info's somewhere in ISO 82000. -- Peter Schaffter https://www.schaffter.ca
Re: Absolute spacing redux
On Thu, Oct 07, 2021, G. Branden Robinson wrote: > At 2021-10-06T00:31:56-0400, Peter Schaffter wrote: > > I believe groff needs a dedicated request for unambiguous absolute > > spacing . > I didn't play with your demo yet, but the first thing that comes to my > mind is that a _request_ might not be the best syntactical place to > locate this extension from a language design standpoint. Might it make > more sense as a new measurement modifier? Quite possibly. > As "|" means "absolute" (in its idiosyncratic way) maybe the > reckoning you're proposing could use a prefix of "@". At first glance, a good choice. '.sp @2i' But see below. > It doesn't need composability with "|", if I understand you, and > outside of the few places where "|" is already recognized, it > doesn't need to be exposed anywhere else. There's the problem of .rt, though, when it's called without an argument. When it has an arg, it might as well be .sp, so the proposed @ works. Without an arg, how do we signal "return unambiguously to the last .mk'd location," which, moreover, is .rt's expected behaviour, according to the info docs: "The 'rt' request returns _upwards_ to the location marked with the last 'mk' request." So we'd still need a new request. Maybe .@rt if @ is adopted for .sp? Or a new arg? '.rt @'? Or the .rt issue could be swept under the carpet with some additional documentation. The info bit, above, with "...subject to variations in vertical spacing that may be introduced by outputting diverted material whose vertical spacing differs from the one in effect when .rt is called." I'm being ironic, of course, but it does expose the scope of the problem. > The other question that troubles me, as many of you will have predicted, > is one of lexicon. Me, too. > What are we going to _call_ these "|" and "@" modifiers? We can > take over "absolute positioning" for "@" if we want, and document > our deviation from CSTR #54 in a footnote[2]. Maybe the harder > problem is what to then call the "|" modifier that we will have to > continue to support indefinitely. "Absolute positioning" is an Orwellianism. '.sp 1i' is absolute; '.sp |1i' is relative (to the top of the page). I wouldn't recommend it. Perhaps there's no need to call | and @ by different names. They (would) do the same thing, just a little differently: "The DIST arg to 'sp' accepts two modifiers, '@' and '|'. '@' positions what follow relative to the top of the page. '|' positions what follows relative to the top of the page plus one linespace." But there's still the .rt problem. -- Peter Schaffter https://www.schaffter.ca
Re: On gripes with refer(1) and it's accumulate setting.
On Fri, Oct 08, 2021, Sigurd Hermann wrote: > I can't refer (easily) to the same book or paper multiple times > without either (1) doing this: > > .[ > $LIST$ > .] > > and then doing the reference again, with a different page number, but > this is annoying, since unless I plan ahead it can look weird. > > I want to do this: > > .\" pretend of course that I've included whatever bibliography file > .\" before citation > .[ > Standard ML > %P 50--75 > .] > .[ > Standard ML > %P 89--120 > .] It's hard to judge, but it looks as if the solution you're seeking might be .[ [ Standard ML .] 50-75) Assuming you have bracket-label " (" ")" ", " or similar in your .R1/.R2 block, the [ before "Standard ML" tells refer(1) to print an opening parenthesis. The text after .] replaces the closing parenthesis, allowing you to cite the page range. Notice that you have to add the closing parenthesis yourself after the page range. The example is for MLA citations. If you use, say, APA style, it would look like this .[ [ Standard ML .] , pp. 50-75) Alternatively, you could create a database record for Standard ML that omits the %P, in which case your .[ Standard ML %P 50-75 .] or similar should work. It depends on where the reference is going (footnote, endnote, parenthetical insertion) and the style guide you're following. In cases where the style guide demands that bibliography or List of Works Cited entries include the number of pages in a work (i.e., it requires a %P field), the first suggestion is the way to go. If number of pages doesn't need to be included in the bibliography entry, the second is preferable. Hope this helps, at least a little. I agree about the refer(1) manpage. In my case, it required considerably more than three readings. It's so dense that every time I opened it, I found myself thinking, "Did someone forget to uncompress the file?" It's like Jello without the water. There was a thread earlier this year about refer(1). I may return to it. -- Peter Schaffter https://www.schaffter.ca
Make pdfbackground less noisy
Deri -- Is there a way to suppress the diagnostics pdfbackground spits out? mom files processed with pdfmom are already saddled with pointless "can't transparently output node at top level" messages emanating from groff. pdfbackground adds even more noise, making it difficult to spot genuinely useful messages and warnings. -- Peter Schaffter https://www.schaffter.ca
Re: Make pdfbackground less noisy
On Tue, Oct 19, 2021, Deri wrote: > On Tuesday, 19 October 2021 17:16:32 BST Peter Schaffter wrote: > > Is there a way to suppress the diagnostics pdfbackground spits out? > I think the noise has been removed in current version in git > master. It has. I was using an older version. -- Peter Schaffter https://www.schaffter.ca