Re: man Macro Package and pdfmark
Hi Werner, Werner LEMBERG wrote on Mon, Feb 17, 2020 at 12:21:43AM +0100: >> And at this point, the man(7) language is better maintained and >> appears to have more of a future than texinfo, which has been a lame >> duck now for at least half a decade, probably longer: > Uh, oh, no idea why you bash texinfo from time to time. Oops, sorry, i didn't intend to start a flame war; the main reason for posting was that i think considering info(1) the modern replacement for man(1) and hence texinfo(5) for man(7) seems doubtful, and part of what the OP wrote felt as if he implicitly came from that assumption. In particular, i didn't intend to discuss the command line UI; that's rather distinct from the markup language and not so much what the OP probably had in mind, given that he mostly wanted to create PDF output. > Currently, it receives more active development than groff - or man(7); > have a look at > > http://git.savannah.gnu.org/cgit/texinfo.git Indeed, it has consistently between 200 and 900 commits per year in every year since 2002. Groff tends to get 50 to 500, mandoc 100 to 400, so the sum of groff and mandoc is of about the same order as texinfo, and only a fraction of that is about man(7), so i was wrong about that point. I *thought* i had looked it up at some point in the past, but it appears i made a mistake when looking it up or when remembering the result. > Almost all GNU programs still provide its documentation in the texinfo > format; I don't see that this will change in the near future. [...] > This AsciiDoc thing never happened Well, my personal impression is that texinfo(5) is likely better than AsciiDoc, so i wouldn't necessarily consider it a bad thing if that's not the direction that is taken. I mainly read that statement by esr/rms as an indication that the GNU project intended to give up on texinfo; interesting to hear that no longer seems likely to you right now. So i should probably be more careful about what i say about texinfo in the future: neither dead nor moribund, it seems. Yours, Ingo
Re: man Macro Package and pdfmark
On Monday, 17 February 2020 13:32:36 GMT Dave Kemper wrote: > Considering that groff's own documentation is (perversely? ironically? > choose your own adverb) written in Texinfo format, a discussion of the > merits of that format could be considered on topic here (if a bit > academic, since no one is champing at the bit to port groff's manual > to any other format). Well! A couple of years ago I had a go! I wrote a script which converted the info, ms, and man formats to a file you can run through groff with the ms macro. The result is here:- http://chuzzlewit.co.uk/groff_book.pdf Not sure there is any real benefit, just the satisfaction of knowing groff can produce its own documentation! Cheers Deri
Re: man Macro Package and pdfmark
On Mon, Feb 17, 2020 at 08:56:25PM +1100, John Gardner wrote: > That's not what I'm talking about. In Emacs, I'm used to smashing `c-h o` > to bring up the documentation for the symbol at point. In info(1), I've no > idea where or what to even begin searching for to find a symbol's > documentation. info(1) without Emacs feels like a fish out of the water. I mean, I'm not info(1)'s greatest fan, but it's really not that bad if you spend a trivial amount of time reading its own docs, which it points you at at the bottom of the screen when you start the program. For example, under "Index Commands", "i", "I", and "M-x index-apropos" seem helpful. FWIW, I'm not even slightly an emacs fan (nor user). -- Colin Watson [cjwat...@debian.org]
Re: man Macro Package and pdfmark
> I won't say more on this topic. We are on a groff list.
Considering that groff's own documentation is (perversely? ironically?
choose your own adverb) written in Texinfo format, a discussion of the
merits of that format could be considered on topic here (if a bit
academic, since no one is champing at the bit to port groff's manual
to any other format).
I'm personally indebted to whoever on this list first pointed out that
you can pipe info(1) through less(1) and view the entire groff manual
as one long page. This has been a godsend and is the only way I've
accessed the groff manual over the past 5+ years.
I hacked together a sed script that further pares it down by, among
other things, removing all the macro-package-specific stuff (the only
macro packages documented in info format are ones I don't use, but
which gave me false positives when using less's search) and the
various indexes (redundant in this format but making up about a third
of the line count). In case it's useful to anyone else:
alias infogroff="info groff |
sed -E '/^[0-9] Macro Packages/,\
/Prev: Macro Packages, *Up: Top$/\
{/Prev: Macro Packages, *Up: Top$/!d};
/^[0-9.]+ .gtroff. Output/,\
/Prev: gtroff Output, *Up: File formats$/\
{/Prev: gtroff Output, *Up: File formats$/!d};
/^Appendix A Copying This Manual$/,\$d;
s/^File: [^,]+, +(Node: [^,]+),.+/\1/' | less"
No idea whether this works with a non-GNU sed, or any shell besides bash.
Re: man Macro Package and pdfmark
> ??? Have you actually used stand-alone `info` recently? In its > standard configuration, you only need the arrow keys together with the > enter key to navigate. That's not what I'm talking about. In Emacs, I'm used to smashing `c-h o` to bring up the documentation for the symbol at point. In info(1), I've no idea where or what to even begin searching for to find a symbol's documentation. info(1) without Emacs feels like a fish out of the water. To Texinfo's credit, it *is* decent at producing well-structured and neatly typeset manuals (going by my copy of *Programming in Emacs Lisp*, which was generated from Texinfo). Its output is, IMHO, best when it's confined to one long page (for easier searching); I have the HTML versions of GNU manuals bookmarked for that reason. However, none of the above merits can't already be achieved with a well-written macro package in Troff, either. On Mon, 17 Feb 2020 at 20:38, Werner LEMBERG wrote: > > >> The info stuff alienates anyone who is not an emacs fan > > > > The standalone info(1) program, though? Please. I'm not going to > > learn a second set of keybindings just to navigate online help. > > ??? Have you actually used stand-alone `info` recently? In its > standard configuration, you only need the arrow keys together with the > enter key to navigate. The tab key also works quite similar to most > GUI applications to move from one field to the next. As with `less`, > the space key moves one page down, the backspace key one page up. You > press 's' to do a search. For compatibility with `less`, you can even > press the '/' key to start a search. > > >> The info stuff alienates anyone who is not an emacs fan. > > This might have been true ten years ago, but it definitely is no > longer today. Please, I ask everyone to do a fact check before > stating things that are simply not true. > > I won't say more on this topic. We are on a groff list. > > > Werner >
Re: man Macro Package and pdfmark
>> The info stuff alienates anyone who is not an emacs fan > > The standalone info(1) program, though? Please. I'm not going to > learn a second set of keybindings just to navigate online help. ??? Have you actually used stand-alone `info` recently? In its standard configuration, you only need the arrow keys together with the enter key to navigate. The tab key also works quite similar to most GUI applications to move from one field to the next. As with `less`, the space key moves one page down, the backspace key one page up. You press 's' to do a search. For compatibility with `less`, you can even press the '/' key to start a search. >> The info stuff alienates anyone who is not an emacs fan. This might have been true ten years ago, but it definitely is no longer today. Please, I ask everyone to do a fact check before stating things that are simply not true. I won't say more on this topic. We are on a groff list. Werner
Re: man Macro Package and pdfmark
I don't know that I have the oomph to do it but one of the things I wanted to do in my retirement was convert all the stuff that is in debian back from info to man(7). I *hate* info. It has made Linux less available to a lot of people. On Mon, Feb 17, 2020 at 02:07:58PM +1100, John Gardner wrote: > > The info stuff alienates anyone who is not an emacs fan > > I'm an Emacs fan, and I also find the Info system abhorrent and confusing. > It's a different story if you're using Emacs, because the Info system is > well-integrated and as easy to navigate as any other buffer (and most Emacs > users will have customised keybindings at that point, so browsing help > isn't weird and confusing). > > The standalone info(1) program, though? Please. I'm not going to learn a > second set of keybindings just to navigate online help. > > Let's face it: the beauty of the man page format is its straightforwardness > and simplicity. Neither of which the Info system has. > > On Mon, 17 Feb 2020 at 13:52, Larry McVoy wrote: > > > On Mon, Feb 17, 2020 at 12:21:43AM +0100, Werner LEMBERG wrote: > > > > > > > And at this point, the man(7) language is better maintained and > > > > appears to have more of a future than texinfo, which has been a lame > > > > duck now for at least half a decade, probably longer: > > > > > > > > > > Uh, oh, no idea why you bash texinfo from time to time. > > > > I rarely post here but I'm definitely in the man page format over texinfo > > camp. Info means you have to learn emacs to navigate. Guess what? > > A lot of the world loves vi over emacs but the vi guys did not make you > > learn vi to read docs. > > > > The info stuff alienates anyone who is not an emacs fan. That's why > > people don't like info. Documentation should be inclusive, info is > > exclusive. > > > > -- --- Larry McVoy lm at mcvoy.com http://www.mcvoy.com/lm
Re: man Macro Package and pdfmark
> The info stuff alienates anyone who is not an emacs fan I'm an Emacs fan, and I also find the Info system abhorrent and confusing. It's a different story if you're using Emacs, because the Info system is well-integrated and as easy to navigate as any other buffer (and most Emacs users will have customised keybindings at that point, so browsing help isn't weird and confusing). The standalone info(1) program, though? Please. I'm not going to learn a second set of keybindings just to navigate online help. Let's face it: the beauty of the man page format is its straightforwardness and simplicity. Neither of which the Info system has. On Mon, 17 Feb 2020 at 13:52, Larry McVoy wrote: > On Mon, Feb 17, 2020 at 12:21:43AM +0100, Werner LEMBERG wrote: > > > > > And at this point, the man(7) language is better maintained and > > > appears to have more of a future than texinfo, which has been a lame > > > duck now for at least half a decade, probably longer: > > > > > > > Uh, oh, no idea why you bash texinfo from time to time. > > I rarely post here but I'm definitely in the man page format over texinfo > camp. Info means you have to learn emacs to navigate. Guess what? > A lot of the world loves vi over emacs but the vi guys did not make you > learn vi to read docs. > > The info stuff alienates anyone who is not an emacs fan. That's why > people don't like info. Documentation should be inclusive, info is > exclusive. > >
Re: man Macro Package and pdfmark
On Mon, Feb 17, 2020 at 12:21:43AM +0100, Werner LEMBERG wrote: > > > And at this point, the man(7) language is better maintained and > > appears to have more of a future than texinfo, which has been a lame > > duck now for at least half a decade, probably longer: > > > > Uh, oh, no idea why you bash texinfo from time to time. I rarely post here but I'm definitely in the man page format over texinfo camp. Info means you have to learn emacs to navigate. Guess what? A lot of the world loves vi over emacs but the vi guys did not make you learn vi to read docs. The info stuff alienates anyone who is not an emacs fan. That's why people don't like info. Documentation should be inclusive, info is exclusive.
RE: man Macro Package and pdfmark
Ingo, > From: Ingo Schwarze [mailto:schwa...@usta.de] > Sent: Sunday, February 16, 2020 2:26 PM Free Software? -- > Oh. Seeing you ask a question about the formatting of a manual page > on a public list concerned with free software, i jumped to the conclusion > that you wanted to publish this page as a part of some free software > package. Sorry for that. Of course there is nothing wrong with using > free software in any way that is convenient for private purposes. Well, I make the program available for free to anyone who wants it (it's not exactly a high-demand item; it calculates illuminance from the Sun and Moon). And untold hours of help using it. It could end up as free software; at present, I'm not sure the code is ready for prime time. It's not exactly bad code, but it looks, shall we say, inelegant compared to what's in the groff package. The interest so far in the scientific community who use it has been for something in Python or R; perhaps not a bad idea, but having little facility in the former and none in the latter, I won't be the one to do it. texinfo --- > And at this point, the man(7) language is better maintained and appears > to have more of a future than texinfo, which has been a lame duck now > for at least half a decade, probably longer: > > https://www.mail-archive.com/groff@gnu.org/msg08172.html The big advantage texinfo has is very extensive links, including bookmarks, cross-references, and clickable index entries. I chose to add some of this capability to a man page; the "page" is 35 pages long, and the program has 42 options, so it's pretty unwieldy without modern navigational aids (some might consider it unwieldy even with the aids). Perhaps I just need to regard it as a "man page" in name only. MKS man(1) and groff > > ... (the MKS man command doesn't appear to format anything, > > expecting formatted files to reside in */cat? directories as on most > > Unix systems long ago). > Heh. That's one man(1) implementation i have most likely never seen. > They even provide a fairly details reference manual online: > > https://www.mkssoftware.com/docs/man1/man.1.asp > And indeed, below FILES, it says: > > man[0-9]/*.[0-9] > unformatted reference pages. > Note: >Unformated reference pages are not currently supported. >Reference pages stored in these directories are treated >as pre-formatted pages. It doesn't quite work like this ... formatted pages only work in the cat* directories. In the man* directories, they're met with contempt. I have a support request in ... Apparently the cat* directories have long gone by the wayside. It's been a while since I've used a real Unix system; in the early 1990s with HP-UX, formatted man pages were kept in the cat* directories. By default, pages weren't formatted until first called for with man(1); in those days, a page could take 30 seconds to format. We'd run /etc/ catman after every update to format all the pages so the users wouldn't need to wait; the process usually took a few hours. And the formatted pages--complete with character-backspace pairs--took a lot of disk space. Things have obviously changed ... > But this page lists groff: > > https://www.mkssoftware.com/docs/cmd_index.asp > > So the tools are there, and the gap shouldn't be too hard to close > for you! ;-) But they haven't actually provided groff for years, at least for the entry-level Toolkit version I have. And it was an ancient version even when they did. Meanwhile, back at the ranch ... Anyway, thanks to everyone for the helpful suggestions. Had I known about Deri's pdfman, I probably wouldn't have bothered with what I've done here. Of course, that would not have eliminated the previous evil macros that I've had for ages :-) Jeff
Re: man Macro Package and pdfmark
> And at this point, the man(7) language is better maintained and > appears to have more of a future than texinfo, which has been a lame > duck now for at least half a decade, probably longer: > Uh, oh, no idea why you bash texinfo from time to time. Currently, it receives more active development than groff – or man(7); have a look at http://git.savannah.gnu.org/cgit/texinfo.git Almost all GNU programs still provide its documentation in the texinfo format; I don't see that this will change in the near future. With some care the results can be quite nice. For example, see the LilyPond notation reference at http://lilypond.org/doc/v2.19/Documentation/notation.pdf And here's the HTML output, generated from exactly the same texinfo source files:[1] http://lilypond.org/doc/v2.19/Documentation/notation/index.html > https://www.mail-archive.com/groff@gnu.org/msg08172.html This AsciiDoc thing never happened – maybe it gets some momentum right now, see https://www.heise.de/developer/meldung/Arbeitsgruppe-zur-Auszeichnungssprache-AsciiDoc-gestartet-4660580.html Werner [1] LilyPond uses a heavily modified, ancient version of the texi2html script, not compatible with the one that is part of current texinfo versions. We lack the manpower to update it... But it still does its job, and the HTML output looks quite nice, too.
Re: man Macro Package and pdfmark
Hi Jeff, Jeff Conrad wrote on Sat, Feb 15, 2020 at 03:45:16PM -0800: > I neglected to mention that the page is for a very specialized command > and is unlikely to exist in other than PDF format except on my system. > Everyone using it so far is running Windows, so no one is likely to say > "man ". Oh. Seeing you ask a question about the formatting of a manual page on a public list concerned with free software, i jumped to the conclusion that you wanted to publish this page as a part of some free software package. Sorry for that. Of course there is nothing wrong with using free software in any way that is convenient for private purposes. > Perhaps man(7) format wasn't the best choice, but it was a quick (and > perhaps dirty) way to provided some documentation that might not > otherwise have been provided. A couple of people mentioned the lack of > bookmarks, which does seem pretty lame for 2020. Perhaps a better > alternative would be to rewrite the page in texinfo to avoid confusion, > though in this context, I'm not sure the effort is justified. And at this point, the man(7) language is better maintained and appears to have more of a future than texinfo, which has been a lame duck now for at least half a decade, probably longer: https://www.mail-archive.com/groff@gnu.org/msg08172.html > Anyway, thanks for the observation, which I might have not thought of > (one person did ask about a Linux port). Using the MKS environment, I > sometimes forget that most *nix environments have diverged considerably > from mine in the last 15 years (the MKS man command doesn't appear to > format anything, expecting formatted files to reside in */cat? directories > as on most Unix systems long ago). Heh. That's one man(1) implementation i have most likely never seen. They even provide a fairly details reference manual online: https://www.mkssoftware.com/docs/man1/man.1.asp And indeed, below FILES, it says: man[0-9]/*.[0-9] unformatted reference pages. Note: Unformated reference pages are not currently supported. Reference pages stored in these directories are treated as pre-formatted pages. But this page lists groff: https://www.mkssoftware.com/docs/cmd_index.asp So the tools are there, and the gap shouldn't be too hard to close for you! ;-) Yours, Ingo
Re: man Macro Package and pdfmark
On Saturday, 15 February 2020 23:45:16 GMT Jeff Conrad wrote: > > Sent: Saturday, February 15, 2020 8:01 AM > > > > It's non-portable because that other person might use a man(7) formatter > > that doesn't support .am or .pdfbookmark, or not in the same way as groff. > > > > > What's far more nonstandard ... > > > > Yes, that is very evil. Never try to be clever in manual page source > > code. Strictly stick to what man(7) documents. > > > > Individual manual pages are not the place to develop new formatting > > features. > > I neglected to mention that the page is for a very specialized command > and is unlikely to exist in other than PDF format except on my system. > Everyone using it so far is running Windows, so no one is likely to say > "man ". It's in man(7) format mainly as a convenience. It's > obvious, perhaps, that it should not be distributed for installation in > a normal man directory (unless perhaps already formatted). > > Perhaps man(7) format wasn't the best choice, but it was a quick (and > perhaps dirty) way to provided some documentation that might not > otherwise have been provided. A couple of people mentioned the lack of > bookmarks, which does seem pretty lame for 2020. Perhaps a better > alternative would be to rewrite the page in texinfo to avoid confusion, > though in this context, I'm not sure the effort is justified. And I > suppose someone might complain that there's no info, which I don't have > and cannot test. > > Many of my man pages include extensions like those in an-ext.tmac; some > have the same names but behave differently. Some of these go back 30 > years when an-ext.tmac didn't exist, so I really didn't have a choice. > Perhaps that's now not good, but I don't have a great urge to go back > and update everything. In most cases, this works to no great evil > because most of the commands are only for my use. But I guess I should > be careful to provide formatted versions the few times I send them to > others. > > Anyway, thanks for the observation, which I might have not thought of > (one person did ask about a Linux port). Using the MKS environment, I > sometimes forget that most *nix environments have diverged considerably > from mine in the last 15 years (the MKS man command doesn't appear to > format anything, expecting formatted files to reside in */cat? directories > as on most Unix systems long ago). > > Jeff Hi Jeff, Given your use case, wanting to provide a pdf which documents a specialsed command for windows users, you might like to try running it through the attached program as a pre- processor before calling groff. I.E.:- pdfman | groff -Tpdf -k -mandoc > your_man_page.pdf (Add your extra personal macros as required). You can see an example of the sort of documents this produces by pointing your browser at:- http://chuzzlewit.co.uk/WebManPDF.pl/man:/7/groff_mdoc I hope this is useful. Cheers Deri pdfman Description: Perl program
RE: man Macro Package and pdfmark
> Sent: Saturday, February 15, 2020 8:01 AM > > It's non-portable because that other person might use a man(7) formatter > that doesn't support .am or .pdfbookmark, or not in the same way as groff. > > What's far more nonstandard ... > Yes, that is very evil. Never try to be clever in manual page source > code. Strictly stick to what man(7) documents. > > Individual manual pages are not the place to develop new formatting > features. I neglected to mention that the page is for a very specialized command and is unlikely to exist in other than PDF format except on my system. Everyone using it so far is running Windows, so no one is likely to say "man ". It's in man(7) format mainly as a convenience. It's obvious, perhaps, that it should not be distributed for installation in a normal man directory (unless perhaps already formatted). Perhaps man(7) format wasn't the best choice, but it was a quick (and perhaps dirty) way to provided some documentation that might not otherwise have been provided. A couple of people mentioned the lack of bookmarks, which does seem pretty lame for 2020. Perhaps a better alternative would be to rewrite the page in texinfo to avoid confusion, though in this context, I'm not sure the effort is justified. And I suppose someone might complain that there's no info, which I don't have and cannot test. Many of my man pages include extensions like those in an-ext.tmac; some have the same names but behave differently. Some of these go back 30 years when an-ext.tmac didn't exist, so I really didn't have a choice. Perhaps that's now not good, but I don't have a great urge to go back and update everything. In most cases, this works to no great evil because most of the commands are only for my use. But I guess I should be careful to provide formatted versions the few times I send them to others. Anyway, thanks for the observation, which I might have not thought of (one person did ask about a Linux port). Using the MKS environment, I sometimes forget that most *nix environments have diverged considerably from mine in the last 15 years (the MKS man command doesn't appear to format anything, expecting formatted files to reside in */cat? directories as on most Unix systems long ago). Jeff
Re: man Macro Package and pdfmark
Hi Jeff, Jeff Conrad wrote on Fri, Feb 14, 2020 at 08:14:15PM -0800: > Ingo Schwarze wrote: >> Jeff Conrad wrote: >>> .am SH >>> .pdfbookmark 1 "\&\\$*" >>> .. >>> .am SS >>> .pdfbookmark 2 "\&\\$*" >>> .. >> Just don't do that. Never use low-level roff stuff in manual pages, >> don't even think about it. This makes your manual pages non-portable. > I'm not quite sure I follow. This code is at the beginning of the file; > thereafter, the markup is standard man(7). If I send my file to someone > else, it should work just fine. It's non-portable because that other person might use a man(7) formatter that doesn't support .am or .pdfbookmark, or not in the same way as groff. > If I make the changes to an-old.tmac, anyone to whom I send the file > would need a nonstandard an-old.tmac for the bookmarks to work. Of course groff improvements will only take effect for users once a groff release is made and integrated into their operating system. But that's the case for any change of any software. > What's far more nonstandard is my use of several forms of pdfhref to > link section references and www references. They need to be wrapped in > macros to handle output other than PDF. Is this bad? Yes, that is very evil. Never try to be clever in manual page source code. Strictly stick to what man(7) documents. Individual manual pages are not the place to develop new formatting features. Yours, Ingo
RE: man Macro Package and pdfmark
Ingo, > Sent: Friday, February 14, 2020 10:46 AM > > .am SH > > .pdfbookmark 1 "\&\\$*" > > .. > > .am SS > > .pdfbookmark 2 "\&\\$*" > > .. > > Just don't do that. Never use low-level roff stuff in manual pages, > don't even think about it. This makes your manual pages non-portable. I'm not quite sure I follow. This code is at the beginning of the file; thereafter, the markup is standard man(7). If I send my file to someone else, it should work just fine. If I make the changes to an-old.tmac, anyone to whom I send the file would need a nonstandard an-old.tmac for the bookmarks to work. What's far more nonstandard is my use of several forms of pdfhref to link section references and www references. They need to be wrapped in macros to handle output other than PDF. Is this bad? Having played with the man page after adding them, it's tough to imagine not having them. I was actually thinking of redoing my documentation for one esoteric program in texinfo. I now think it will be OK with man. > If you want bookmark support for PDF output from man(7) files, that > needs to be done in the file an-old.tmac, but in a careful way that > does not cause incompatibilities I agree that an-old.tmac is the right place to do this; there's the added advantage that the call to pdfbookmark can be made before the heading text is output, eliminating the need to adjust the value of PDFHREF.VIEW.LEADING. But it seems to me that the right way to do it is in the distribution so that a man page that relies on it will work anywhere. > and that does not require including any other macro files. It may be > tricky, but it may well be possible. As it turns out, there is nothing tricky about it. I discovered that the pdfmark macros are defined in pdf.tmac, so there's no need to load pdfmark.tmac. Mystery Messages It turns out that the problem arises from the leading zero-width glyph in my call of pdfmark: .pdfbookmark 1 "\&\\$*" changing this to .pdfbookmark 1 "\\$*" gets rid of the messages. The protection is unnecessary anyway, because the macros already provide it. So just don't do it. Don't even think about it. However it's done, the bang for the buck seems pretty high. Jeff
Re: man Macro Package and pdfmark
Ingo Schwarze wrote in <20200214184532.gj92...@athene.usta.de>: |Hi Jeff, | |Jeff Conrad wrote on Thu, Feb 13, 2020 at 03:45:10PM -0800: | |> A major drawback to manual pages formatted using the man macros is the |> lack of bookmarks in a PDF file. A quick and dirty way to get bookmarks |> appears to be adding |> |> .am SH |> .pdfbookmark 1 "\&\\$*" |> .. |> .am SS |> .pdfbookmark 2 "\&\\$*" |> .. |> |> to the beginning of the man page source | |Just don't do that. Never use low-level roff stuff in manual pages, |don't even think about it. This makes your manual pages non-portable. | |If you want bookmark support for PDF output from man(7) files, |that needs to be done in the file an-old.tmac, but in a careful |way that does not cause incompatibilities and that does not |require including any other macro files. It may be tricky, |but it may well be possible. Yes, i have already mailed him in private. It actually takes four lines of code and produces good results, i could not reproduce his problems. I asked him whether he wants to open an issue, i for myself will add (at least) the four lines when i finally, finally come to my own roff port. --steffen | |Der Kragenbaer,The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)
Re: man Macro Package and pdfmark
Hi Jeff, Jeff Conrad wrote on Thu, Feb 13, 2020 at 03:45:10PM -0800: > A major drawback to manual pages formatted using the man macros is the > lack of bookmarks in a PDF file. A quick and dirty way to get bookmarks > appears to be adding > > .am SH > .pdfbookmark 1 "\&\\$*" > .. > .am SS > .pdfbookmark 2 "\&\\$*" > .. > > to the beginning of the man page source Just don't do that. Never use low-level roff stuff in manual pages, don't even think about it. This makes your manual pages non-portable. If you want bookmark support for PDF output from man(7) files, that needs to be done in the file an-old.tmac, but in a careful way that does not cause incompatibilities and that does not require including any other macro files. It may be tricky, but it may well be possible. Yours, Ingo
Re: man Macro Package and pdfmark
Jeff Conrad wrote in : |A major drawback to manual pages formatted using the man macros is the |lack of bookmarks in a PDF file. A quick and dirty way to get bookmarks |appears to be adding | |.am SH |.pdfbookmark 1 "\&\\$*" |.. |.am SS |.pdfbookmark 2 "\&\\$*" |.. Why quick and dirty? I am using this regulary for my mdocmx(7) macros on top of normal mdoc(7) with groff 1.22.3 (since i have not ported the enhance request to 1.22.4): .de mx:dump-anchor-pdf . \" Outline support . ie '\$1'Sh' .pdfbookmark 1 "\$3" . el .if '\$1'Ss' .pdfbookmark 2 "\$3" . . ie d mx-debug \ . pdfhref M -N "\$2" -E "#\$2#" . el \ . pdfhref M -N "\$2" .. |to the beginning of the man page source (the PDFHREF.VIEW.LEADING |register needs a slight increase to make the heading texts visible when |clicking a bookmark). | |But this results in the message | |"... can't transparently output node at top level"; | |if there are many sections and subsections, there are a lot of messages. I see exactly five such messages with a huge manual page with 666 anchors and thousands (!) of links. |It doesn't seem to cause much harm--the PDF bookmarks are duly created-- |but the messages are distracting, and may make it easier to miss a real |error. I don't get the messages if I call pdfbookmark directly from the |man page source rather than adding them to the macros; this certainly is |a solution, but it does require a fair bit of extra coding that adds |clutter to the document source. For mdoc macros there are a lot of other messages which are distracting, however. |I've looked at pdfmark.tmac and a couple of the groff source files, but |haven't been able to figure out what's happening. | |I get the same message using spdf (e.g., formatting the pdfmark |reference manual); is this just something one does not worry about? That is an interesting question. --steffen | |Der Kragenbaer,The moon bear, |der holt sich munter he cheerfully and one by one |einen nach dem anderen runter wa.ks himself off |(By Robert Gernhardt)
