Hi Ingo, At 2025-01-24T07:47:00+0100, Ingo Schwarze wrote: > G. Branden Robinson wrote on Wed, Jan 22, 2025 at 08:47:20PM -0600: > > At 2025-01-22T07:10:54+0100, Ingo Schwarze wrote: > >> It does not require the user to provide any new configuration or > >> options. It happens completely automatically and transparently > >> whenever the user types "man pagename" or "apropos -a > >> search_expression". > > > Right. I'll need to expose a mechanism via the man(7) interface > > (albeit **NOT** that used for authoring documents) so that the > > man(1) program can exercise it. (Again, see [1].) mandoc(1) > > controls both ends of that pipeline; groff does not. > > Correct. That doesn't mean that mandoc is monolithic, though. [snip]
Wasn't suggesting that it was. :) Simply that you can coordinate with yourself in a much tighter loop than I can with Colin Watson. > [...] So a line of text is hardly longer than what a human reader > instantly recognizes anyway (except when using insane line lengths > like 100-200 characters; i never understood how people who use such > wide terminals manage to keep track of which line they are currently > reading in the first place). Me neither! Years ago I used to tolerate this and found myself much happier when I forced an 80-column limit on man pages I viewed. Since joining groff development I've embraced a 72-column limit in much of my work. > [...] > > But your mandoc(1) > > has "man -T html"...how do you solve the problem of ambiguous tags > > _there_? I'm going for a general solution; I'm trying to solve the > > tagging/linking problem for HTML, PDF, and the terminal all at once. > > Trivially: if a tag occurs for the first time, just use it as-is. > When a tag occurs the second time, append the suffix "~2". > The third time, append "~3", and so on. Ah, okay; I had something less hackish and with more likely long-term stability in mind. With this approach, a tag name is highly dependent on what else one is rendering with it in the same run. However, earlier in the thread we identified both man page structure and content (particularly at the level of individually documented syntax items) as inherently in flux, so my aspiration for an unambiguous tag naming convention may be forlorn anyway. > [...] > >>> I also don't happen to know how ctags(1) got extended to support > >>> C++ name spaces and other means of qualifying colliding identifier > >>> names. But if ctags (perhaps Exuberant ctags, given the original > >>> ctags format's advanced age) got extended to cope with that > >>> problem, presumably less(1) learned how to interpret the > >>> extension. > > >> Not that i'm aware of anything like that, no. Also, given that > >> ctags(1) is mandated by POSIX and less(1) aims for portability > >> (AFAIK), relying on extensions might be a bad idea. > > > Exuberant ctags's extensions are ubiquitous. > > Is that so? Yes, when starting to use mg, I ran into them immediately in multiple projects. Probably Debian's default ctags implementation is "Exuberant" or descendant from it. > Personally, i have implemented a generator for ctags(1) files (in > mandoc) and i'm using that frequently. But i don't recall ever having > heard the word "Exuberant" as a name of a person or organization. The world didn't stop when Ken Arnold stopped turning it. ;-) https://docs.ctags.io/en/latest/man/ctags.1.html > HISTORY > The ctags command appeared in 2BSD. > > STANDARDS > The ctags utility is compliant with the IEEE Std 1003.1-2008 > (“POSIX.1”) specification, though its presence is optional. > > The flags [-BdFuvw] are extensions to that specification. > > Support for Pascal, YACC, lex, and Lisp source files is an IEEE > Std 1003.1-2008 (“POSIX.1”) extension. The standard notes that > ctags is "not required to accommodate these languages, although > implementors are encouraged to do so". > > I don't see anything about non-BSD authors there. I even checked > the complete commit log for the directory and see medium amounts of > maintenance work being fone there, but no indication of non-BSD > contribution oder feature additions for compatibility. This doesn't shock me. After Arnold's first cut, BSD curses stayed right where it was for many years as well, despite a gets()-style vulnerability in its `getstr()`. > ??? > > I admit that mandoc supports several options that are POSIX extension, > but -k is mandated by POSIX: [...] > So fortunately, man-db and mandoc agree about the basic meaning > of both -a and -k. That's hardly a coincidence though: [...] > So, while man-db clashes *with itself* in so far -a has > two conflicting meanings in man(1) and apropos(1), it actually > agrees with mandoc (as far as that is still possible despite > its internal conflict). > > Please avoid adding options to man(1) if you can, and if you > cannot avoid it, then *please* do consult > https://mandoc.bsd.lv/man/man.options.1.html > before doing so in order to minimize the risk of clashes. I have no plans to tell Colin how to expose an interface to tag usage. The job I've chosen for myself is to implement the feature on the formatter/macro package side. I'm confident he'll have sensible ideas about how to exercise it. > > If one wants to select a subset of tags of interest, I guess that's > > where the analogue of mandoc(1)'s "-ak" comes in. > > Hmmm, no. I'm not even sure what "subset of tags of interest" > is supposed to mean. The meaning of -ak i simply "display all > pages matching the following search expression". That's precisely what I mean. Note that "man -k ." should match essentially all man pages. On my system, piping that through "wc -l" yields a number around 17,500. > When formatting few pages at a time, say up to several hundred at > the same time, i don't recall ever having seen such problems, it > seems the likelihood is just too low at small scales. groff 1.22.4 and earlier had big problems when typesetting a man(7) page, then an mdoc(7) page, and a man(7) page again. It's now been years since I cleaned this stuff up and no longer recall details. They're in the Git history. I don't remember any of it requiring formatter changes. Just revisions to macro package internals. > I *could* sometimes reproduce such problems by formatting just two or > three pages in a specific order, but actually hitting such problems in > practice seems to usually require thousands of pages. With thousands > of pages, it has happened to me once every few years, which is > annoying enough that i remember and fear it. =:c/ I wrote automated tests to _make_ them happen, so that I would have more confidence in my changes. 3:-) > >> Still, running commands like > >> $ man -ak ~. > >> can be useful for finding bugs. By the way: > >> $ man -ak ~. | col -b | grep -c ^NAME > >> 8801 > >> $ time man -ak ~. > >> 0m17.16s real 0m15.07s user 0m01.18s system > >> $ time doas makewhatis > >> 0m10.58s real 0m08.96s user 0m01.35s system > > > How many separate Unix processes are involved in doing that, though? > > ;-) > > Exactly one, no parallelization or multithreading whatsoever. Not sure that was the scenario I was wondering about, but your statement makes sense as applied to the example you show. > > nroff(1) and man(1), going back to early editions of CSRC Unix, are > > built around the filter model and pipe(2). It's long been known > > that context switches are expensive, mode switches more expensive > > still > > Admitted. > > $ time for in in $(jot 100); do man -c true; done > 0m00.83s real 0m00.01s user 0m00.02s system > > Since the size of the true(1) manual is almost zero, that - eight > milliseconds for one page - is almost entirely process setup overhead, > and that's about four times the CPU time required to format an > average-sized (i.e. much larger) manual page. Man page rendering time on the terminal seems largely to be a solved problem. If I ever need to attack its performance in groff, I will, but that will likely come after Deri James's 9000x linear tag search performance monster--my own spawn, apparently--stalks up to confront me face to face. (Rising up like Cronus to his father?) On the bright side, after grappling that beast, I should have adequate skill to cope with mildly deficient man page rendering performance, should that problem eventuate. > > I monitor mandoc(1)'s cvsweb closely and can't remember when > > I've seen a change that caused me concern. If I ever do, I'll > > let you know. > > Appreciated! :) > > If you want to receive the mandoc commits automatically via mail, > i can subscribe you to the source@ mailing list, just let me know. > Some information about the lists is at > > https://mandoc.bsd.lv/contact.html Consider me interested! > >> Updating the groff port in OpenBSD causes a horrendous amount of > >> work - so much so that i still didn't manage to update to > >> groff-1.23 in the OpenBSD ports tree, mostly due to large amounts > >> of subtle changes in behaviour between 1.22.4 and 1.23. Before > >> being able to update, i have to disentangle and classify all those > >> changes as follows: > >> > >> 1. Desirable effects of bugfixes and of changes making groff > >> behaviour saner or more consistent; some of these require > >> adjustments in mandoc, too, and/or maybe in the test suite. > > > I indeed hope that the great preponderance of problems are of this > > kind. > > Not really. By far the largest class is class 3 (build system > issues). Class 1 and 2 (good vs. harmless gratuitious changes) > might be about on par - though i'm not completely sure yet, as > i'm still struggling to classify the large amount of issues. Bummer. I've gotten happier with groff's build system over time, not more frustrated. Part of that may be a result of contorting myself to accommodate it, however. > >> 2. Trivial changes that aren't necessarily intentional, but > >> only affect unimportant edge cases such that they can stay. > >> A few of these may requires adjusting mandoc, too, and > >> several require asjusting the test suite. > > > I'm curious to know about these if you'd care to record them. They > > might not be things I want to change or revert, but they might bring > > my attention to consequences I hadn't considered, and maybe I can > > anticipate similar impacts in the future. > > Some of these are already fixed in mandoc or its test suite, > and i did not keep a list about those. But i think i can produce > such a list after committing the groff port, because i certainly > note in the commit message when a tweak is motivated by a change > in groff. I'll keep a curious eye out. > >> 3. Build system hiccups. These typically require setting > >> configure or make(1) variables in the ports Makefile, but > >> diagnosing what exactly is needed is typically hard. > >> A few extreme cases might require patches. > >> Due to extensive use of GNU autotools and gnulib, this > >> class of problems is particularly large and annoying. > > > I can't claim credit/blame for restructuring groff around Autotools > > and Gnulib, but I'll accept responsibility for not changing it. For > > non-BSD systems they deliver remarkably little hassle. > > > > I should bring your attention to: > > > > https://savannah.gnu.org/bugs/index.php?66518 > > Yes, i'm aware of that, and that will likely result in further > degradation of portability. :( > There are three reasons why i didn't mention my doubts about that > earlier: > (1) In theory, the idea of a standardized approach to portability > sounds good, so it's hard to argue with that. The problem is not the > basic idea, but that gnulib is overzealous *and* overengineered to > such an extent that the end result is nothing short of catastrophic. I don't know if I agree with this. It could be argued that OpenBSD deliberately wraps itself in a lot of straight jackets, in the name of security and other concerns. Witness that OpenBSD's own projects aren't written to be portable to anything except OpenBSD itself. If you want OpenSSH or LibreSSL on some other kernel, you must confine your activities to a sort of portability anteroom. I don't condemn that arrangement; it's probably accomplishing what it was meant to, as highlighted last year with the XZ Utils social engineering attack. But I don't think I'm using gnulib inappropriately or even aggressively (apart from tossing out libgroff's long-toothed duplication of facilities it provides). So I would say that this point is a social and technical cost that OpenBSD's mission and philosophy are imposing on its own developers. It may be well be worth paying, but should be admitted to instead of castigating the rest of the world's approach to portability libraries, which will necessarily have to interface with a lot of crazy systems with a wide variety of defects and eccentricities as "overzealous" and "overengineered". I'm not expressing an original thought when I note that when you target only one system, you can write much leaner code. > (2) libgroff isn't exactly code of stellar quality either, so it's > equally hard to argue that getting rid of it would be a bad idea. I > think the low code quality in libgroff (IIRC) also caused a very small > number of build failures in the (remote) past, but that was mostly > before your time, and both much rarer and much less severe and much > easier to fix than gnulib issues. IIRC there may have on the order of > one to three issues with libgroff, grand total, ever - in > groff-1.23.0, there are at least a dozen issues right now, maybe more. I seem to remember there being some grief around the "hypot" module around the time of the 1.22.4 release. I didn't feel I understood it at the time. I might now, maybe, if I bothered to review it. It's not my job to defend libgroff's code quality, but as I've committed to slimming it down, there may end up being less of it to wrinkle your nose. Replacing `strsave()` with `strdup()`, which was not standard and perhaps not even widely known in 1989, is some obvious low-hanging fruit. > (3) I spent less time on mandoc and groff lately than in some previous > years and hence missed some stuff - and was leass eager to make a > fuss. > > [...] > > I see commits from Bruno with respect to FreeBSD 11, NetBSD 7.1, > > and OpenBSD 6.0 within the past month (in time to make gnulib's > > 2025-01 stable tag). > > OpenBSD 6.0? That's... hilarious. > > $ uname -a > OpenBSD isnote.usta.de 7.6 GENERIC.MP#496 amd64 > > OpenBSD 6.0 is more than 8 years old and has been EOL and unsupported > for more than seven years now. > > Supported FreeBSD releases currently are 13.4, 14.1, and 14.2. > FreeBSD 11 was released in 2016 and EOL in 2021. > > Supported NetBSD releases currently are 9.4 and 10.1. > NetBSD 7.x was released in 2017 and EOL 2020. > > So if your observation summarizes the situation adequately and if > i'm not missing something, I think you're jumping to a conclusion. The fact that these old releases were recently tested and made to work with gnulib does not imply that they are _the most recent releases_ of those systems to receive such attention. That doesn't follow at all. I'm responsible for prompting two portability fixes to g++ 5.5/Solaris 11/SPARC64 in the past year. That doesn't mean gnulib hasn't paid attention to anything that's happened since October 2017 (GCC 5.5 released). > that would mean that only bugs are getting fixed that were reported at > least seven years ago and affect operating system versions that are no > longer supported for at least seven years. Not sure what to make of > that, i didn't try to work with the gnulib folks and i'm not > particularly eager to try, either, given how their code looks. In any > case, getting groff to build at all is clearly more important than > trying to help fix gnulib - which might well be a lost cause anyway, > even if the maintainers are freindly and well-intentioned and work > hard. I suspect the trouble stems more from basic design principles > and development goals than from individual bugs or oversights. If you could direct me to a portability library that you feel is done well, and that offers comparable coverage to gnulib, I'm curious to have a look at it. > > I'd happily try {Free,Net,Open}BSD builds myself, but the FSF > > France's compiler farm hosts for these OSes are down/unresponsive > > every time I try them. > > I have no access to any FreeBSD or NetBSD machines. I do have some > OpenBSD machines, but none of those can be used for testing purposes. > I have sent a crashing build log in private mail to you, though. Thanks. Dave Kemper's done some solid QA work that should avoid embarrassment in groff 1.24.0.rc1. It's taking some effort to address the issues he's raised. > >> 4. Regressions. These require pushing bugfixes to groff, > >> plus patches in the ports tree until they get released. > > > I definitely want to know about these ASAP. Or do you mean the ones > > I've already noted and committed, kicking them up to "Important" > > severity in Savannah? > > Some may already be fixed, not sure i have reported all yet. > I will definitely show you a complete list of patches we use > once the port is ready, and that includes patches for all bugs > fixed in the port. > > I'm also working on reducing patches and instead adding lines > to groff site configuration files, as intended by groff developers, > where possible. This is music to my ears! Even if you don't arrange for them to be editable (after the fashion of Debian's "conffiles", such migration will make it easier for users to discern where formatter and package defaults have been overridden. Those files are where the man pages tell them to look. [snip] > > I'm not happy to hear that. Apart from not using Gnulib or the GNU > > build system, both of which I prefer to retain because I perceive > > them of _relieving_ me of maintenance overheads (which is their > > reason for existing in the first place), I'm keen to hear your > > suggestions for things I can do that will reduce the pain. > > Yes, that's definitely the plan to aim for providing feedback in a more > specific and more constructive manner. > > I'm wasn't really expecting that suggesting to ditch gnulib would be > met with enthusiasm. Even though i suspect that the *real* portability > issues groff needs to deal with require less than 1% of the behemoth > of code included from gnulib, simply because i suspect that groff > portability needs are very modest, given that groff doesn't exactly > use all the most modern features in its code base, even though i'm > quite sure that going for a simple, straightforward scheme like the > one used by mandoc, with one static configure script that is written > fully by hand and never regenerated, which produces a grand total of > 52 lines of output, and which take the replacement implementations > from OpenBSD instead of from glibc, such that they are typically > a fraction of the size and don't typically contain any preprocessor > directives, would significantly improve groff portability *and* > significantly reduce your workload - i still fear that might not > very well fit into GNU philosophy and hence not be all that welcome, > even if it would be undeniably efficient. I don't know of anyone who's in love with Git's submodule approach. Not that finding an alternative would completely address your grievance--but it would help. > I mean, just look at the list of systems on which mandoc runs: > > https://mandoc.bsd.lv/ports.html All of these look like POSIX systems to me.[1] Gnulib also tries to work on Windows systems (groff once did), and, I think, even VMS. > > By contrast, specimens like Illumos troff are seldom worth > > mentioning. It's just Solaris 10 troff under a different name, and > > its development community seems to have its focus utterly on other > > aspects of the system. > > Is troff in Illumos still relevant for what we are discussing here? Not, I suppose, if no one ever cares to run groff on it. > Illumos folks told me in 2014 that they started using mandoc(1) for > manual page formating at that point instead of *roff, even though, > last time i checked, they still used Solaris man(1) as the viewer. > > So like many Linux systems use groff+man-db, for all i know, > Illumos uses mandoc+Solaris-man, and by the way, MacOS now > uses mandoc+FreeBSD-man. As noted earlier in the thread, the tagging problem, if solved properly in my opinion, involves but is not limited to man(7) and mdoc(7). So I must keep non-man-page typesetting concerns in mind. > > Heh, as you're probably aware, I use a "Notes" section myself, in 3 > > of groff's pages. > > > > 1. In nroff(1), because of the SGR problem. A lot of the same > > people who insist that groff not produce SGR escape sequences > > will not ever think to look in grotty(1). (Incidentally, this > > same page uniquely _lacks_ an "Options" section; a piloted your > > approach to see what I thought of it.) > > Hmmm, that's indeed a tough case because that information hardly > belongs into the nroff(1) page, and consequently there probably isn't > any good place at all - but i still see why you want it there. > Shallow wrapper programs (like nroff) are often hard to document > properly because most of the information users need for using them > does not belong in the manual page of the wrapper but into the various > other programs that the wrapper wraps. It's a dilemma resulting from > dubious API design involving too many abstractions and layers. This is a shadow cast by history. nroff of course was not originally a wrapper around anything. In principle, groff could throw nroff away, but then we'd get a lot of users wondering where it went; a non-trivial number of projects expect an nroff program to be on the system. Many use it to generate text dumps of man pages, apparently on the principle that their package will not be installed such that the user can easily format the man page from source for themselves (or perhaps the fear is that too much knowledge will be required for them to do so). Once upon a time, "man -l filename" was not something you could do. Adding the "NOTES" section to nroff(1) was not a compromise I made in anticipation of problems or a desire to duplicate material, but a calibrated response to cries of anguish from frustrated users. (Specifically, those registering their complaints in the Debian BTS, since Debian's users are culturally shy about filing bug reports with upstream vendors.) > > 2. In groff_me(1), to explain the origin of the package's name. > > The page is otherwise pretty terse and businesslike, and more an > > aide-mémoire than a true reference, so I saw no other good place > > to put it. > > I tend to think the first sentence of those NOTES (the one about > single-letter names) belongs into the HISTORY section of groff_tmac(5). > Most of the second sentence belongs in the AUTHORS section, which > should probably also say something like "reimplemented for groff > by James Clark in 198x". groff me(7) is not a reimplementation. The package was freely licensed (and no longer actively maintained), so Clark incorporated it into groff's distribution. There _was_ some minor divergence in the early 1990s as Keith Bostic and others firmed up 4.4BSD. I "rebased" the handful of commits they made into groff's me(7) for our 1.23.0 release. > A few bits near the end of the second sentence belongs in the HISTORY > section, which should probably say something like > > The me macros first appeared in 2BSD. That's a worthy suggestion. > Since groff is not primarily used in BSD communities, many groff > users might not understand what the somewhat cryptic "2BSD" means, > so maybe something like > > ... in the second Berkeley Software Distribution (2BSD), > released in May 1979. Personally, I expect groff users who care anything about history to be aware of BSD. When populating "HISTORY" sections for the ncurses man pages, I generally couple a Unix release with its calendar year. For example, getstr(3NCURSES): HISTORY 4BSD (1980) introduced wgetstr along with its variants. SVr3.1 (1987) added wgetnstr, but none of its variants. X/Open Curses Issue 4 (1995) specified getnstr, mvgetnstr, and mvwgetnstr. > So here, i really see no need for NOTES. If I add a "HISTORY" section to groff_me(7), I agree that I can probably squeeze its origin story in there. > > 3. In groff_man_style(1), as a kind of FAQ. I won't apologize for > > this; I need it to dispel myths and confusion. I _could_ call > > it something else; its present name seems good enough. > > You got me there. A style guide in manual page form is so unusual > that some unusual decisions might be called for. Also, a style > guide, in particular when it is long, might prioritize pedagogy > over conciseness and rigour, in which case my argument that every > topic needs to be discussed in exactly one place breaks down and > afterthoughts may become legitimate. Looks like you may have found > an example unusual enought that even a NOTES section can be defended. I get no feedback on that FAQ material; I suppose it's either working extremely well or being ignored entirely. In fact, I seldom get feedback on the content of any of groff's man pages, except on occasion from familiar figures like Dave Kemper. > > Ah! I forgot to mention `TQ`. Yes, it's completely my intention to > > treat `TQ` the same as `TP` in this respect. > > > > But not for `IP`. That macro seems, somewhat preponderantly, to > > already be getting used as a non-semantic, or differently semantic, > > device, to mark lists with symbols or enumerators. (It's more > > structural than semantic, we might say.) That's good. I want to > > encourage and reinforce that practice. > > Maybe. Given that both serve almost the same purpose - the main > difference only being that .TP supports macros in the tag and .IP does > not - some style guidance regarding when to use which one might make > sense. Deprecating .IP outright doesn't seem like a good idea because Whoa, hold up there. I have no plans at all to deprecate `IP`. I don't think that's feasible. In fact: * I'm on the brink (in terms of personal resolve) of un-deprecating `HP`. I think groff's historical case against it is more a case of papering over groff's poor HTML story than anything else. Yes, it's a style macro rather than a semantic one. And yes, the caveat about distinctions being lost if the paragraph ends up getting set on only one line is significant, and should be retained. But `LP`, `PP`, and `P` already mean the same thing. For a short paragraph (where "short" depends both on the textual content and the rendering environment), what's one more synonym? Whenever I roll up my sleeves and try to solve grohtml's deeper problems, then as far as I know `HP` will be an easy case of applying a CSS style to the relevant paragraph element. * I don't plan to ever withdraw support even for macros currently deprecated, including the SunOS 4 `SB` extension, which is superfluous on modern formatters. (And would have been on old ones too, if only Joe Ossanna had made `it` work like `ce` and `ul`. Alas, alack!) > .TP > \(bu > text body > > is very ugly, and bullet+numbered lists is a reasonable scope that > works well with the .IP syntax. I agree, that's why people should be using `IP` for that instead. [rearranging] > So you would be punishing end users for something that was > considered OK in the past and that documentation maintainers and > code generator maintainers need to fix - possibly before knowing > whether documentation maintainers will even agree with your position. I don't regard "failure to leverage a new feature" as "punishment". Nothing that works now will work _worse_ as a result of this policy. I think a more appropriate term is "motivation". > However, even in the OpenBSD tree, which does not contain particularly > many man(7) manuals, significant numbers of manual pages contain > long tag arguments after .IP macros. Most of these are GNU manuals. I suspect these were produced by "help2man", the use of which I keep running into when studying GNU projects. It's an unsatisfying compromise (in my opinion) between Stallman's extreme allergy to man pages and corresponding insistence that every one share it on the one hand, and the Debian Project's insistence that all commands have man pages (a principle to which it has not shown great fidelity). I've looked at help2man, and begun pondering how I might help that project out. We'll see what eventuates, if anything. I only have so many round tuits. > Even worse, pod2man(1) emits .IP, not .TP, for tagged lists. pod2man users might counter that they _already_ have tags exactly where they want them, thanks to all those `IX` macro calls that the rest of the world delusionally thinks useless. So we'll see who's actually upset about it. ;-) > Here is a list of some manual pages affected, where users won't > have tags (or at least less tags) because of your policy on .IP: > addr2line(1) ar(1) as(1) c++filt(1) ld.bfd(1) objdump(1) readelf(1) > objcopy(1) strings(1) readline(3) mkhybrid(8) and almost all > Perl manual pages. > On top of that, all FVWM manual pages, editres(1), sessreg(1), twm(1), > xbacklight(1), xedit(1), xpr(1), xrandr(1), xsetroot(1), XF86VM(3), > Xsecurity(7), and almost all X11 section 3 library manuals. I seem to remember that you find the X11 man pages severely defective in a lot of other respects. > From a random collection of a few ports i have currently installed: > arara(1), bib2gls(1), bzless(1), python3.12.1(1), practically all > FFmpeg manuals, afm2afm(1), albatross(1), autoinst(1), curl(1), > cvs2cl(1), dvipng(1), epstopdf(1), gslp(1), install-tl(1), > luafindfont(1), mk-ca-bundle(1), ofm2opl(1), ovf2ovp(1), pedigree(1), > ps2pk(1), repstopdf(1), thumbpdf(1), ttf2afm(1), unzip(1), updmap(1), > and all the GnuTLS manuals ... > > So not providing support before deprecation takes effect may not > be the friendliest move. I appreciate you cataloging these, and it's a list to which I expect to return. I suspect a lot of these man pages are autogenerated by a tool, so the solution is to fix the tool generating them. The X11 man pages are an exception; I know from my past life an XFree86 package maintainer that most of those are written by hand. I think the Open Group had notions of unifying all X documentation around Rosetta Man/PolyglotMan but never got that off the ground. A good thing, as "rman" had license problems. At the time, TOG didn't mind those. I don't expect to have the time to bite off _another_ titanic man page reform effort until after I've finished my current one with ncurses, which has been underway for about 16 months (earlier this month I submitted 177 patches). I'd estimate I have another year ahead of me. Maybe less; I'm starting to see light at the end of the tunnel for the core library, and while the form and menu libraries have voluminous content, they also have much more formulaic content, more susceptible to scripted revision, and _vastly_ less complicated histories than curses proper. (The panel library's documentation is one big page.) > [...] > > NEWS: > > * The an (man) macro package now supports a `TS` register to > > configure the minimum space required between the tag of a `TP` > > paragraph and its body. (If the width of the tag's formatted > > text plus this space exceeds the paragraph indentation, the line > > is broken after the tag.) This parameter, formerly hard-coded as > > `1n`, now defaults to `2n`. > > > > * The an (man) macro package's `IP` macro no longer honors the > > formerly hard-coded 1n tag separation noted in the previous item. > > This means that the first argument to the `IP` macro can abut the > > text of the paragraph with no intervening space. If you use a > > word instead of punctuation or a list enumerator for `IP`'s first > > argument, consider migrating to `TP`. > > Regression suite fun at the horizon for the 1.24.0 ports update. Sorry. :( These aren't whimsies but efforts to improve readability and to give the man page author (and reader) flexibility. > > I haven't brought this to your attention before now because I > > expected you to: > > > > A. Ignore the `TS` register entirely; and either, > > Certainly, but the change of the default is likely to cause a few > hours of work on the mandoc and test suite sides. > > > B1. Go along with my tweak to indentation, or > > Probably (because off the top of my head, i suspect it makes .TP more > similar in style to .Bl -tag), but i'm not sure yet. > > > B2. Not, overriding it with a patch. > > Unlikely, i somewhat dislike patches for trivial tweaks like that. > > If it turns out it causes more serious trouble than just churn, > there is a third possibility: > > B3. Harass you for a revert, even if i'm late to the party. I pray not. I'd sooner help you out with updating your test suite. > [...] > >>> For man(7) the `MR` macro new to groff 1.23 was an obvious > >>> site to add the appropriate machinery for document-level > >>> links. mdoc(7)'s `Xr` is closely analogous and has existed > >>> for many years. > > >> Yes, both have almost identical semantics and are a likely > >> candidate for extension, if we come to the conclusion an extension > >> is needed. I didn't consider the details yet, though. > > > I think you were discussing `SX`/`Sx` here? As I understand it, > > `MR` support is already in mandoc(1) CVS (but not released), as of > > course is `Xr`, for some years. > > I guess you misunderstand. I did not mean "add .MR as an extension" - > that has indeed been agreed and implemented already. I meant "extend > the existing .MR and .Xr macros with another argument or something > like that". Oh. No. I don't plan that. I couldn't see a way to implement it that didn't upset my stomach. > > Also, you can't put a price on the pleasure of introducing a macro > > named `SX`. It pleases the 13-year-old in everyone. > > I scratched my head for some time what you even meant here before > finally getting it - even though it works in German exactly like > in English. I think i wouldn't have noticed that even as a teenager, > neither as 13-year old nor as a 19-year old. You were raised in a less puritanical society than I was. ;-) > And no, i wasn't talking about .Sx. The .Sx macro is for local > links inside one page. Right. > But here you want to design a macro to link from one page to another. > That's what .MR/.Xr do, so those are the first candidates that come to > mind for extension. Yes, but if we don't try to support "deep" linking, there's nothing to support. > Also, extending .Sx for that purpose doesn't seem easy, since it > already accepts an arbitrary number of arguments (e.g. .Sx SEE ALSO). Right. A similar problem would afflict a man(7) `SX` analogue. > Number theorists may feel comfortable reasoning about the number > omega+2 - computers get very nervous when you ask them to handle it, > they don't even like omega itself all that much. Hah! > [...] > > While deep structural links risk encouraging stagnant man page > > structures, deep unstructured links will promote retention of > > features. And there are enough forces favoring the latter. Our > > industry has a bad problem with not throwing old cruft away. > > OpenBSD suffers from that problem less than other projects. > Ted Unangst (tedu@) has earned such a high reputation and so much > respect for excising large amounts of code from all over the tree > that "teduing" has become a neologistic synonym for "cleaning up". > LibreSSL is among the most active parts of the OpenBSD tree, and > currently, at least 80% of the work done there is teduing (during > the first two year of development, it felt more like 98%). > That still holds even though Ted U. is currently no longer involved > in LibreSSL (he was years ago and is among the founding members > of LibreSSL precisely because he wanted to tedu there, and indeed > he did so. > > I'm not convinced we should let speculations about possible effects > on people's bad habits influence the deep linking design - that > design task is difficult enough without additional non-technical > constraints. Besides, i doubt that the design of deep linking > can really improve people's willingness to tedu. Okay. I'm fine with this perspective. And also I've learned a new verb. unangst, v.t.: To eliminate the presence of code causing one angst. > > Using English instead of machinery might remain our most robust > > technology. "See the “-h” option in ksh(1)." > > That's exactly what Jason McIntyre (jmc@) and myself have been > doing in OpenBSD for decades, and i'm not aware of any problems > it may have caused. > > > For URLs (and email addresses), it's already in place. We use OSC > > 8. > > Yikes. ANSI X3.64. The nightmare. Also known as ECMA-48 and ISO 6429. I fear it not. I think it's a tameable beast. But I do not claim that all implementations _have_ tamed it. They should apply fuzz testers and supply evidence. > Reminds me the we ought to disable ANSI X3.64 support in OpenBSD > xterm(1) by default. It already does nothing with OSC 8. The bad behavior (and plagiarism) of developers involved with gnome-terminal have left a poor taste in Thomas Dickey's mouth. I have my own ideas for getting OSC 8 support into xterm that won't compromise the principles Thomas has articulated, but I will have a tall job of salesmanship to achieve. And that's not good, because I know from experience that I am a _terrible_ salesman. > It's just too dangerous due to the very lange number of escape codes > that make it hard to secure and the fact that many of them can wreak > havoc. A manual page viewer is a typical example of a program that > must be able to run securely, even as root, and that must not, under > any circumstances, make the terminal window unusable. It might > contain the last available shell on a remote machine that is in > trouble, and reading the manual page may be needed to implement a fix > for whatever problem there is. I agree that a man page renderer will plausibly be run in desperate straits. That is one reason I want the content and rendering of man pages to be of high quality. It sometimes happens that one is reading a page when one's margin of overhead for BS has been completely consumed. > But manual pages are essentially untrusted data, so allowing a > manual page viewer processing manual pages to send dangerous > escape codes to a terminal is not acceptable. Maybe you argue > "well, the manual page viewer must not *pass through* escape > codes, but there is no risk in *creating* certain escape codes > from scratch" - but that violates the principle of multi-layer > security. Sanitize input and reject ANSI X3.64 contained in > the manual page. AND sanitize output, making sure that you never > create ANSI X3.64. I've foreclosed another conceivable channel for that in the forthcoming groff 1.24. commit f0ef2a7074f7cea3a6484bbe77127b397cafa362 Author: G. Branden Robinson <g.branden.robin...@gmail.com> Date: Sun Dec 8 12:56:10 2024 -0600 [troff]: Fix Savannah #66546 (`cf` is unsafe). Disable `cf` request in safer mode. * src/roff/troff/input.cpp (copy_file): Do it. * doc/groff.texi.in (I/O) <cf>: * man/groff.7.man (Request short reference) <cf>: * man/groff_diff.7.man (Restricted requests): Do it. * NEWS: Add item. Fixes <https://savannah.gnu.org/bugs/?66546>. > AND make sure that the pager always ignores ANSI X3.64, i.e. never run > it with -r or -R. That's a policy decision. > AND make sure all potentially dangerous ANSI X3.64 codes are disabled > in the terminal emulator - and that certainly includes OSC 8. I would > go so far that not only should the "Operating Sytem Command" ANSI code > (as a whole, not just OSC 8) be disabled by default, but the > possibility to enable it should be patched out of xterm(1) lest users > do that by accident when editing xterm(1) config files or blissfully > ignorant of the risks - as in "oh, colour sounds nice, let's do that". > > Multi-layered security actually provides security. Artful > arrangement of slices of swiss cheese such that (hopefully?) the > holes never align is a recipe for disaster. That's why you don't want your arrangement of Swiss cheese slices to be merely artful. You should _test_ them. Having _faith_ that your multi-layered security approach, achieved by following a script of forbiddances and prohibitions, is just as much an act of unempirical hope as "well, this feature configuration _seems_ to work and we don't _know_ of any attacks". Your percentage _might_ be better but it's a far cry from exhaustive testing or verification by formal methods. "Only two remote holes in the default install, in a heck of a long time!" I understand what you're selling. It's a difference of degree, not kind. But, even if no one avails themselves of OSC 8 man page hyperlinks, either because they run xterm(1), or they don't recognize that's what they are, or they have fear that "man:ls(1)" will do something horrific, or because their vendor has disabled the groff feature, the grotty(1) work (OSC 8) was a pretty small piece of the whole. We have PDF hyperlinks in man pages now and I _know_ that's nice because I've used them myself. But back on the gripping hand, yeah, a lot of users will wonder why you'd ever render a man page to PDF in the first place. Some people just will not ever care about typesetting. > > If less(1) strips that (it doesn't) or the terminal doesn't support > > it, the user doesn't get hyperlinks. Okay, so they're no worse off > > than before. > > In short, we have no solution for the task we set out to solve, > right? Deep linking? Guess not. > [...] > > • What’s the difference between a man page topic and > > identifier? > > > > A single man page may document several related but distinct > > topics. For example, printf(3) and fprintf(3) are often > > presented together. > > What you call "topic" here is called "name" in the mandoc(1) > documentation. Maybe not a huge problem because the mandoc > documentation does not define a term "topic" at all, so there > is no clash. > > > Moreover, multiple programming languages have functions named > > “printf”, and may document these in a man page. The > > identifier is intended to (with the section) uniquely > > identify a page on the system; it may furthermore correspond > > closely to the file name of the document. > > What you call "identifier" here is called "title" in the mandoc > documentation. Mandoc treats the title a an additional name; > for that reason, the man(7) page in the mandoc package takes the > shortcut of presenting this synopsis: > > .TH name section date [source [volume]] > > Of course, the title usually matches one of the other names, > and often the first one, though that is not necessary. That's why I prefer to distinguish them. Take the ncurses man page "attr", for example. On my system it installs as $DESTDIR/share/man/man3/attr.3ncurses. Its `TH` call looks like this: .TH attr 3NCURSES 2025-01-18 "ncurses 6.5" "Library calls" ...so "attr" is the "identifier" in groff man parlance. Yet "attr", by itself, _does not appear_ in the "Name" section, because no C symbol name corresponds to it. (Despite curses's propensity to micturate freely all over the C symbol name space.) attr(3NCURSES) Library calls attr(3NCURSES) NAME attr_get, wattr_get, attr_set, wattr_set, attr_off, wattr_off, attr_on, wattr_on, attroff, wattroff, attron, wattron, attrset, wattrset, chgat, wchgat, mvchgat, mvwchgat, color_set, wcolor_set, standend, wstandend, standout, wstandout - manipulate attributes of character cells in curses windows > The stipulation that the "identifier is unique within the section" > is completely unrealistic in practice, on Linux even more than on > *BSD. The package manager *can* make sure that two packages do not > in install a file into the same file system path, clobbering each > other. A man page's location on the system is utterly outside my power. I'm just the rendering guy. Resolution of an identifying tuple to one or more file names on the system is the librarian's job. > And indeed, package managers often do check that - sometimes already > by flagging such clashes in a centralized package database in the > build system infrastructure of the operating system developer, > requiring packages to be fixed or marked as conflicting when they > clash, such that both cannot be installed at the some time. Some > other package managers also or only do such checks of not overwriting > existing files owned by other packages at install time, and refuse > installing when encountering conflicts. Right. Not my bailiwick. The macro package and the formatter have no power or influence over these matters. > But i have not heard of package managers attempting to parse manual > pages and try to detect *logical* conflicts in the *content* of manual > pages. That would seem very hard to implement and in addition > rather fragile and inefficient. Even Marc Espie's pkg_add(1) > packet manager in OpenBSD, which spends a lot of effort on > handling documentation with special care, does not do that - > and it would also be wrong to do that, because .TH/.Dt clashes > cause no problem and are simply legitimate. I don't understand what point of mine you are rebutting here. > > The man(1) librarian makes access to man pages convenient by > > resolving topics to man page identifiers. > > That is not true and misleading. In your terminology, the correct > statement would be: > > The man(1) librarian makes access to man pages convenient by > resolving each topic to one or more fully qualified file system > paths to manual page files. Mmm, I guess I could say: The man(1) librarian makes access to man pages convenient by resolving topics to man page identifiers and thence to file names on the system. > That is not only true for mandoc, but for all man(1) implementations > i'm aware of, in particular including man-db. > > > Thus, you can type “man fprintf”, and other pages can refer > > to it, without knowing whether the installed document uses > > “printf”, “fprintf”, or even “c_printf” as an identifier. > > The term "identifier" is badly misleading because multiple > pages with the same "identifier" (or "title" in mandoc terminology) > can exist in the same section of the same manual page tree, and all > those files can even be in the same directory. This does not > prevent man(1) from finding all these files anyway. This doesn't follow. Identifiers are not necessarily, of themselves, unique, and you seem to have the implicit assumption that they are. Consider the entity relationship diagram of a relational database. Multiple tables can have fields with the same name, even when those fields are primary keys. SQL, for example, has means of resolving ambiguities when field names (like "ID") collide. It's not a daunting problem. If an identifier is unique within a name space, you have to say so, often by identifying the name space. It can't be assumed. Not all the world is C. > What really "identifies" a manual page is the fully qualified files > system path - because you cannot have two files with the same filename > in the same directory. You are over-applying concepts and habits you've learned from C. > [...] > > While we don't want to put every tag into the "Name" section so that > > it will be indexed by the librarian-- > > Complete agreement, that would make the NAME section totally > unreadable. I already wince at the length of some of the specimens of "NAME" in the ncurses man pages. But Thomas Dickey has not materially contributed to the problem. It goes back to the System V Interface Definition, which was substantially adopted as-is by X/Open for Issue 4's standard Curses. (X/Open did innovate stuff around wide-character support, to the standard's benefit; the System V Unix people appeared dead set upon stepping on a rake as hard as they could by recapitulating the utter blindness they brought to the widening of 4BSD's curses character type. Typical C programmers. "If I can't represent it in an `int`, it's not worth representing.") SVID's curses man pages got into ncurses around 1995 (perhaps via a vendored Unix release like Solaris 2.3) at the instigation of Eric Raymond, then co-maintainer with Zeyd ben-Halim. Eric asserted, as he often did, that somehow copyright didn't apply to something he wanted to appropriate for one of his projects. In this case, he suggested that a process of "reverse nroff[ing]" documents liberated them of any copyright that applied to them. If Solaris 2.3 or something with broadly similar man(7) sources was in fact what he used, then this "reverse nroff" process seems likely to have a been a sed(1) script that stripped comments[2] and replaced man(7) font selection and alternation macros with roff(7) font selection escape sequences, a move in exactly the wrong damned direction for maintainability purposes. I perceive some word and phrase replacements, some warranted but hardly constitutive of the "originality" that U.S. copyright law requires, and others which seem only to be a feeble effort at covering one's tracks. Typical Eric. See Dickey's page[3] and attachments. Similarly, Eric Raymond had the habit of erasing people's names from code they contributed to him. To his credit, he accurately foresaw and arguably pioneered the contours of sundry "Contributor License Agreements" later corporatized, re-expressed in legalese, and popularized among many "open source" projects, the terms of which amount to "by sending this to us you essentially make it ours, thanks a lot and f*** off". And yet the steady reader of, say, LWN has gotten to enjoy the repeated spectacle over the years of people expressing shock and surprise when the scorpion ultimately exercises its tail, locking up contributions behind a paywall or turning them into subscription-ware. > > indexing all `-h` command line options would be worse than useless-- > > Not true. The makewhatis(8) program in the mandoc package does > exactly that, index all -h command line options in all manual pages, > and you can search for them with man(1) -k, as i demonstrated in an > earlier mail. That's quite useful, too. Huh, okay. Well, mark them with `TP` and I expect groff and man-db man together will achieve parity. > > I think every symbol in a C API should be. > > Yes, even macros and non-function objects. > > Here, we can happily agree to disagree. > > Treating macros that take arguments exactly like functions is fine > because the distinction is a technicality. > > Treating constant macros like functions, however, is over the top. I don't agree with respect to variables and literals. This is what happens when you expose a public symbol. You don't (or should not) get to escape responsibility for it because its "just" a variable or a constant instead of a function. It's part of your API and your ABI, and it materially affects the linkage of every program that involves your library. I will return to preprocessor macros. > In some pages that only mention one or two constants, in might not > cause much grief, but pages exist that document large numbers of > constants. Here is an extreme example that would massively bloat > the NAME section: > > https://man.openbsd.org/errno.2 Yes. But the bloat is already there in the symbol table. By omitting these names from errno(2) we lie by omission, perhaps to reassure ourselves that our system interface is "lean" and "elegant" when it is anything but. People want to defend Unix's reputation so badly that they will dissemble about it to maintain the myths they tell themselves. I dissent. > Constant macros are like wolves, they often come in packs. > Often, one constant requires much less documentation than one > function because it has far fewer moving parts: no arguments, > no return value, no semantics, not even any syntax apart from > the literal name itself. I entirely agree. A constant still exists in the symbol name space nonetheless. (Or _worse_ as a preprocessor macro that has no actual visibility in object code. We've enhanced debugging sections of ELF objects to perform reverse flips through flaming hoops to appease the silly insistence of C programmers that manifest constants are an appropriate application of the preprocessor. They are not. Yes, everybody is taught to do so in their first C programming class. They are taught wrongly. The preprocessor was a terrible hack to get around deficiencies in C's design as a language. C++, true to form, as with type-checking of function calls, accurately diagnosed a deficiency. And also true to form, C++ contrived a solution that was _even worse_, with a metaprogramming templating engine that they didn't even realize was Turing-complete until someone pointed it out. Good God.) > (Exceptions exist where constants do require massive amounts of > documentation because they are essentially abused like functions. > Yes, i'm looking at you, EVP_PKEY_CTX_ctrl(3).) Yes. The job of a man page is to tell the truth about the interface, not conceal the errors of its design. > And finally, significant numbers of constants are used by more than > one function, sometimes even by functions in several manual pages, > which makes the question which manual should have the constant in the > name section rather arbitrary. That's another design flaw. It's worst in the standard C library itself, which wasn't _designed_. It rolled like a sticky ball on a filthy kitchen floor, picking up all kinds of debris. I have no sympathy. If the header file exposes it, you document it. If more than one header file exposes it because of "historical reasons", then you get to document it in each place. If you hate this in your job as a documentor of your system's libc, load up your bucket with thunderbolts, go to WG14, and strike everybody with lightning until they fix the inelegance. And then, even if you prevail, wait one decade for your fix to get into the standard and several more before you can even think of dropping the caveat from your man page. As Hyman Roth said _The Godfather Part II_, "because this is the business we've chosen!" > In mandoc, the whole question is moot anyway because you can say > > $ man -k Er=EINVAL > > and get all 221 manual pages refering to it listed, without needing > it in any NAME section. That's neat, but I'm impressed only if that actually comprehensively and accurately reflects the implementations. If, say, for instance, I wanted to kill off GNU's silly "EIEIO" constant, and a command like that accurately told me everything that emitted it, that'd be damn useful. I suspect in practice we can rely only on static analysis tools or (ugh) source grepping to determine the truth. But if OpenBSD is disciplined enough to represent that truth in its man pages, then the system has my respect. > Simlarly for type names: each type is typically used in many manual > pages, even though some exceptions of specialized types that are only > relevant for a single page do exist. It won't surprise you to know that I'm just as militant here. > > These are "first-class" concerns just like function calls. > > Part of your interface? Document it. > > Absolutely! But not every public symbol needs to be a "topic", > in your parlance (or a manual page name according to mandoc). Here we disagree. As a C programmer I expect freedom in selecting my identifiers. And yet there is no name spacing, so if you're going to constrain my freedom if I use your library or #include your header, the very smallest courtesy you can pay me is to tell me how you're doing so. I have zero sympathy for lazy sod rock star library writers who won't even tell me that much. (Hello, uchardet!) > Sorry for the typo, i meant .Tg (manual tagging), not .Tp, which > indeed does not exist and is not planned. Ahh, yeah. Okay. I'm in much the same place as you. I can _imagine_ an extension macro enabling the man page author to explicitly name a tag identifier, but I could not imagine it being used very much. And the actual experience of mdoc(7) users seems to bear that out. > [...] > > there may be a subtle difference between the ways we're using the > > word "node" here. > > Not subtle at all, it's a drastic difference. > > Here are examples of nodes in mandoc: [deep discussion snipped] > #define ASCII_NBRSP 31 /* non-breaking space */ > #define ASCII_NBRZW 30 /* non-breaking zero-width space */ > #define ASCII_BREAK 29 /* breakable zero-width space */ > #define ASCII_HYPH 28 /* breakable hyphen */ > #define ASCII_TABREF 26 /* reset tab reference position */ This reminds me pretty strongly of GNU troff's "input.h". https://git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/input.h?h=1.23.0 (Now half that length because EBCDIC support is gone.) In GNU troff, a token might become a node very early, or it might remain a character until fairly late in processing. The variation in earliness versus lateness arises from language features like strings, diversions, macros, and "copy mode". Three of those generally delay the translation of tokens into nodes; diversions _make_ the translation happen, sometimes with surprising consequences to advanced *roff users as articulated earlier in the thread. Ultimately, when it is time to produce output, everything becomes a node except for sharp and pointy features that mandoc(1) doesn't have to care about, like "transparent throughput" and "device extension commands". > The reason why mandoc is quite unlikely to ever implement diversions > is that the most central design principle of mandoc is that the > parse tree is guaranteed to be independent of the output device, and > completely finanalized before the program even looks at the question > which output device the user selected. No part of the formatters > can ever be called before the parse tree is fully complete and > immutable. All substitutions (in particular, of user defined macros, > strings and number registers) must be completed before the parsers > can even be started. Whatever is stored in any user defined string > or number register after parsing has started is guaranteed to have no > effect on the output. > > Hence, storing anything produced by the formatters (which can only > by invoked after parsing is complete) into any string or register > (which no longer have any effect if parsing was even started) is > totally out of the questions. I would have to throw away the > most fundamental parts of the software architecture and start over > completely from scratch. Yes, it seems daunting. > > That's why I want a string iterator and well-defined operations to > > identify nodes so that they can be stripped from strings, without > > bespoke formatter features and without hacks. > > Yes, mandoc also contains string iterators in a number of places - > the iteration itslef is so short and straightforward that there > is no abstraction for it even though it's needed at more than one > place. The tricky part is the handling of escape sequences (what > groff would call nodes), implemented in the recursive functions > in the file roff_escape.c and called whenever needed for iteration > or processing. This is a pain I've gotten more familiar with over the years. > > Will we ever need or want type-aware node operations in the groff > > language? Good grief, I hope not. But the mere existence of nodes > > in bona fide language objects has already created pain--esoteric > > pain that produced diagnostic messages that no one on this mailing > > list understood. (Or if they did, they chose not to share > > knowledge.) > > Oh the joys of in-band meta messaging: escape sequences embedded in > plain text strings. Didn't i already get riled up about that very > subject earlier in this message? Yes. If you have a brilliant solution to the problems I presented about PDF metadata and hyperlinks, I'm listening and I'll bet Deri is too. Regards, Branden [1] I don't know what "Unleashed" is, and its hyperlink 404s. [2] Comments like this, for instance. .\" @(#)curs_attr.3x 1.22 93/03/26 SMI; from SVr4 '\"macro stdmacro .\" Copyright 1989 AT&T .\" ident "@(#)svid_ti:ti_lib/curs_attr 1.4" ...which would disclose altogether too much provenance. [3] https://invisible-island.net/ncurses/ncurses-license.html#ncurses_1_8_5
curs_move(3X) curs_move(3X)
NAME
curs_move, move, wmove - move curses window cursor
SYNOPSIS
#include <curses.h>
int move(int y, int x);
int wmove(WINDOW *win, int y, int x);
MT‐LEVEL
Unsafe
DESCRIPTION
With these routines, the cursor associated with the window is moved
to line y and column x. This routine does not move the physical
cursor of the terminal until refresh() is called. The position
specified is relative to the upper left‐hand corner of the window,
which is (0,0).
RETURN VALUES
These routines return the integer ERR upon failure and an integer
value other than ERR upon successful completion.
SEE ALSO
curs_refresh(3X), curses(3X)
NOTES
The header <curses.h> automatically includes the headers <stdio.h>
and <unctrl.h>.
Note that move() may be a macro.
22 Jan 1993 curs_move(3X)
curs_move(3X) curs_move(3X)
NAME
curs_move: move, wmove ‐ move ncurses window cursor
SYNOPSIS
#include <ncurses.h>
int move(int y, int x);
int wmove(WINDOW *win, int y, int x);
DESCRIPTION
These routines move the cursor associated with the window to line y
and column x. This routine does not move the physical cursor of
the terminal until refresh is called. The position specified is
relative to the upper left‐hand corner of the window, which is
(0,0).
RETURN VALUE
These routines return the integer ERR upon failure and an integer
value other than ERR upon successful completion.
NOTES
Note that move may be a macro.
SEE ALSO
ncurses(3X), curs_refresh(3X)
curs_move(3X)
curs_move(3X) curs_move(3X)
NAME
[-curs_move,-]
{+curs_move:+} move, wmove [---] {+‐+} move [-curses-] {+ncurses+} window
cursor
SYNOPSIS
#include [-<curses.h>-] {+<ncurses.h>+}
int move(int y, int x);
int wmove(WINDOW *win, int y, int x);
[-MT‐LEVEL
Unsafe-]
DESCRIPTION
[-With these routines,-]
{+These routines move+} the cursor associated with the window [-is moved-]
to line y
and column x. This routine does not move the physical cursor of
the terminal until [-refresh()-] {+refresh+} is called. The position
specified is
relative to the upper left‐hand corner of the window, which is
(0,0).
RETURN [-VALUES-] {+VALUE+}
These routines return the integer ERR upon failure and an integer
value other than ERR upon successful completion.
[-SEE ALSO
curs_refresh(3X), curses(3X)-]
NOTES
[-The header <curses.h> automatically includes the headers <stdio.h>
and <unctrl.h>.-]
Note that [-move()-] {+move+} may be a macro.
[-22 Jan 1993-]
{+SEE ALSO
ncurses(3X), curs_refresh(3X)+}
curs_move(3X)
signature.asc
Description: PGP signature
