{ "content": [ { "type": "text", "text": "# groff_www(7) (man)\n\n**Summary:** groffwww - groff macros for authoring web pages\n\n**Synopsis:** groff -m www [option ...] [input-file ...]\n\n## See Also\n\n- groff(1)\n- troff(1)\n- grohtml(1)\n- netpbm(1)\n\n## Section Outline\n\n- **NAME** (3 lines)\n- **SYNOPSIS** (2 lines)\n- **DESCRIPTION** (46 lines)\n- **REQUESTS** (1 lines) — 13 subsections\n - .JOBNAME filename (13 lines)\n - .BCL foreground background active not-visited visited (3 lines)\n - .BGIMG imagefile (2 lines)\n - .URL url [description] [after] (18 lines)\n - .MTO address [description] [after] (14 lines)\n - .FTP url [description] [after] (9 lines)\n - .TAG name (12 lines)\n - .IMG [-R|-L|-C] filename [width] [height] (7 lines)\n - .PIMG [-R|-L|-C] filename [width [height]] (6 lines)\n - .MPIMG [-R|-L] [-G gap] filename [width [height]] (69 lines)\n - .DC l text [color] (9 lines)\n - .ALN [color] [percentage] (16 lines)\n - .LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ] (7 lines)\n- **SECTION HEADING LINKS** (4 lines)\n- **LIMITATIONS OF GROHTML** (2 lines)\n- **FILES** (2 lines)\n- **AUTHORS** (3 lines)\n- **SEE ALSO** (5 lines)\n\n## Full Content\n\n### NAME\n\ngroffwww - groff macros for authoring web pages\n\n### SYNOPSIS\n\ngroff -m www [option ...] [input-file ...]\n\n### DESCRIPTION\n\nThis manual page describes the GNU -mwww macro package, which is part of the groff document\nformatting system. The manual page is very a basic guide, and the HTML device driver (‐\ngrohtml) has been completely rewritten but still remains as in an alpha state. It has been\nincluded into the distribution so that a lot of people have a chance to test it. Note that\nthis macro file is automatically called (via the troffrc file) if you use -Thtml or -Txhtml.\n\nTo see the hyperlinks in action, please format this man page with the grohtml device.\n\nHere is a summary of the functions found in this macro set.\n\n.JOBNAME split output into multiple files\n.HX automatic heading level cut off\n.BCL specify colours on a web page\n.BGIMG specify background image\n.URL create a URL using two parameters\n.FTP create an FTP reference\n.MTO create an HTML email address\n.TAG generate an HTML name\n.IMG include an image file\n.PIMG include PNG image\n.MPIMG place PNG on the margin and wrap text around it\n.HnS begin heading\n.HnE end heading\n.LK emit automatically collected links.\n.HR produce a horizontal rule\n.NHR suppress automatic generation of rules.\n.HTL only generate HTML title\n.HEAD add data to block\n.ULS unorder list begin\n.ULE unorder list end\n.OLS ordered list begin\n.OLE ordered list end\n.DLS definition list begin\n.DLE definition list end\n.LI insert a list item\n.DC generate a drop capital\n.HTML pass an HTML raw request to the device driver\n.CDS code example begin\n.CDE code example end\n.ALN place links on left of main text.\n.LNS start a new two-column table with links in the left.\n.LNE end the two-column table.\n.LINKSTYLE initialize default URL attributes.\n\nOutput of the pic, eqn, refer, and tbl preprocessors is acceptable as input.\n\n### REQUESTS\n\n#### .JOBNAME filename\n\nSplit output into multiple HTML files. A file is split whenever a .SH or .NH 1 is\nencountered. Its argument is the file stem name for future output files. This option\nis equivalent to grohtml's -j option.\n\n.HX n Specify the cut off depth when generating links from section headings. For example, a\nparameter of 2 would cause grohtml to generate a list of links for .NH 1 and .NH 2 but\nnot for .NH 3. Whereas\n\n.HX 0\n\ntells grohtml that no heading links should be created at all. Another method for\nturning automatic headings off is by issuing the command-line switch -P-l to groff.\n\n#### .BCL foreground background active not-visited visited\n\nThis macro takes five parameters: foreground, background, active hypertext link,\nhypertext link not yet visited, and visited hypertext link colour.\n\n#### .BGIMG imagefile\n\nthe only parameter to this macro is the background image file.\n\n#### .URL url [description] [after]\n\ngenerates a URL using either one, two or three arguments. The first parameter is the\nactual URL, the second is the name of the link, and the third is optional stuff to be\nprinted immediately afterwards. If description and after are absent then the URL\nbecomes the anchor text. Hyphenation is disabled while printing the actual URL;\nexplicit breakpoints should be inserted with the \\: escape. Here is how to encode foo\n⟨http://foo.org/⟩:\n\n.URL http://\\:foo.\\:org/ foo :\n\nIf this is processed by a device other than -Thtml or -Txhtml it appears as:\n\nfoo ⟨http://foo.org⟩:\n\nThe URL macro can be of any type; for example we can reference Eric Raymond's pic\nguide ⟨pic.html⟩ by:\n\n.URL pic.html \"Eric Raymond's pic guide\"\n\n#### .MTO address [description] [after]\n\nGenerate an email HTML reference. The first argument is mandatory as the email ad‐\ndress. The optional second argument is the text you see in your browser. If an empty\nargument is given, address is used instead. An optional third argument is stuff\nprinted immediately afterwards. Hyphenation is disabled while printing the actual\nemail address. For example, Joe User ⟨joe@user.org⟩ can be achieved by the following\nmacro:\n\n.MTO joe@user.org \"Joe User\"\n\nNote that all the URLs actually are treated as consuming no textual space in groff.\nThis could be considered as a bug since it causes some problems. To circumvent this,\nwww.tmac inserts a zero-width character which expands to a harmless space (only if run\nwith -Thtml or -Txhtml).\n\n#### .FTP url [description] [after]\n\nindicates that data can be obtained via FTP. The first argument is the URL and the\nsecond is the browser text. A third argument, similar to the macros above, is in‐\ntended for stuff printed immediately afterwards. The second and the third parameter\nare optional. Hyphenation is disabled while printing the actual URL. As an example,\nhere is the location of the GNU FTP server ⟨ftp://ftp.gnu.org/⟩. The macro example\nabove can be specified as:\n\n.FTP ftp://\\:ftp.gnu.org/ \"GNU FTP server\" .\n\n#### .TAG name\n\nGenerates an HTML name tag from its argument. This can then be referenced using the\nURL ⟨#URL⟩ macro. As you can see, you must precede the tag name with # since it is a\nlocal reference. This link was achieved via placing a TAG in the URL description\nabove; the source looks like this:\n\n.TP\n.B URL\ngenerates\n.TAG URL\na URL using either two or three arguments.\n...\n\n#### .IMG [-R|-L|-C] filename [width] [height]\n\nInclude a picture into the document. The first argument is the horizontal location:\nright, left, or center (-R, -L, or -C). Alignment is centered by default (-C). The\nsecond argument is the filename. The optional third and fourth arguments are the\nwidth and height. If the width is absent it defaults to 1 inch. If the height is ab‐\nsent it defaults to the width. This maps onto an HTML img tag. If you are including\na PNG image then it is advisable to use the PIMG macro.\n\n#### .PIMG [-R|-L|-C] filename [width [height]]\n\nInclude an image in PNG format. This macro takes exactly the same parameters as the\nIMG macro; it has the advantage of working with PostScript and HTML devices also since\nit can automatically convert the image into the EPS format, using the following pro‐\ngrams of the netpbm package: pngtopnm, pnmcrop, and pnmtops. If the document isn't\nprocessed with -Thtml or -Txhtml it is necessary to use the -U option of groff.\n\n#### .MPIMG [-R|-L] [-G gap] filename [width [height]]\n\nPlace a PNG image on the margin and wrap text around it. The first parameters are op‐\ntional. The alignment: left or right (-L or -R) specifies the margin where the pic‐\nture is placed at. The default alignment is left (-L). Optionally, -G gap can be\nused to arrange a gap between the picture and the text that wraps around it. The de‐\nfault gap width is zero.\nThe first non-optional argument is the filename. The optional following arguments are\nthe width and height. If the width is absent it defaults to 1 inch. If the height is\nabsent it defaults to the width. Example:\n\n.MPIMG -L -G 2c foo.png 3c 1.5c\n\nThe height and width may also be given as percentages. The PostScript device calcu‐\nlates the width from the .l register and the height from the .p register. For exam‐\nple:\n\n.MPIMG -L -G 2c foo.png 15%\n\n.HnS n Begin heading. The numeric heading level n is specified by the first parameter. Use\nthis macro if your headings contain URL, FTP or MTO macros. Example:\n\n.HnS 1\n.HR\nGNU Troff\n.URL http://groff.ffii.org (Groff)\n—— a\n.URL http://www.gnu.org/ GNU\nproject.\nHosted by\n.URL http://ffii.org/ FFII .\n.HR\n.HnE\n\nIn this case you might wish to disable automatic links to headings. This can be done\nvia -P-l from the command line.\n\n.HnE End heading.\n\n.LK Force grohtml to place the automatically generated links at this position. If this\nmanual page has been processed with -Thtml or -Txhtml those links can be seen right\nhere.\n\n.HR Generate a full-width horizontal rule for -Thtml and -Txhtml. No effect for all other\ndevices.\n\n.NHR Suppress generation of the top and bottom rules which grohtml emits by default.\n\n.HTL Generate an HTML title only. This differs from the TL macro of the ms macro package\nwhich generates both an HTML title and an

heading. Use it to provide an HTML ti‐\ntle as search engine fodder but a graphic title in the document. The macro terminates\nwhen a space or break is seen (.sp, .br).\n\n.HEAD Add arbitrary HTML data to the block. Ignored if not processed with -Thtml or\n-Txhtml. Example:\n\n.HEAD \"\"\n\n.HTML All text after this macro is treated as raw HTML. If the document is processed with‐\nout -Thtml or -Txhtml then the macro is ignored. Internally, this macro is used as a\nbuilding block for other higher-level macros.\n\nFor example, the BGIMG macro is defined as\n\n.de BGIMG\n. HTML \n..\n\n#### .DC l text [color]\n\nProduce a drop capital. The first parameter is the letter to be dropped and enlarged,\nthe second parameter text is the adjoining text whose height the first letter should\nnot exceed. The optional third parameter is the color of the dropped letter. It de‐\nfaults to black.\n\n.CDS Start displaying a code section in constant width font.\n\n.CDE End code display\n\n#### .ALN [color] [percentage]\n\nPlace section heading links automatically to the left of the main text. The color ar‐\ngument is optional and if present indicates which HTML background color is to be used\nunder the links. The optional percentage indicates the amount of width to devote to\ndisplaying the links. The default values are #eeeeee and 30 for color and percentage\nwidth, respectively. This macro should only be called once at the beginning of the\ndocument. After calling this macro each section heading emits an HTML table consist‐\ning of the links in the left and the section text on the right.\n\n.LNS Start a new two-column table with links in the left column. This can be called if the\ndocument has text before the first .SH and if .ALN is used. Typically this is called\njust before the first paragraph and after the main title as it indicates that text af‐\nter this point should be positioned to the right of the left-hand navigational links.\n\n.LNE End a two-column table. This should be called at the end of the document if .ALN was\nused.\n\n#### .LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]\n\nInitialize default URL attributes to be used if this macro set is not used with the\nHTML device. The macro set initializes itself with the following call\n\n.LINKSTYLE blue CR \\[la] \\[ra]\n\nbut these values will be superseded by a user call to LINKSTYLE.\n\n### SECTION HEADING LINKS\n\nBy default grohtml generates links to all section headings and places these at the top of the\nHTML document. (See LINKS ⟨#LK⟩ for details of how to switch this off or alter the posi‐\ntion).\n\n### LIMITATIONS OF GROHTML\n\ntbl information is currently rendered as a PNG image.\n\n### FILES\n\n/usr/share/groff/1.22.4/tmac/www.tmac\n\n### AUTHORS\n\nThe www macro package was written by Gaius Mulley ⟨gaius@glam.ac.uk⟩, with additions by\nWerner Lemberg ⟨wl@gnu.org⟩ and Bernd Warken ⟨groff-bernd.warken-72@web.de⟩.\n\n### SEE ALSO\n\ngroff(1), troff(1), grohtml(1), netpbm(1)\n\n\n\ngroff 1.22.4 23 March 2022 GROFFWWW(7)\n\n" } ], "structuredContent": { "command": "groff_www", "section": "7", "mode": "man", "summary": "groffwww - groff macros for authoring web pages", "synopsis": "groff -m www [option ...] [input-file ...]", "flags": [], "examples": [], "see_also": [ { "name": "groff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/groff/1/json" }, { "name": "troff", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/troff/1/json" }, { "name": "grohtml", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/grohtml/1/json" }, { "name": "netpbm", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/netpbm/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 3, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 46, "subsections": [] }, { "name": "REQUESTS", "lines": 1, "subsections": [ { "name": ".JOBNAME filename", "lines": 13 }, { "name": ".BCL foreground background active not-visited visited", "lines": 3 }, { "name": ".BGIMG imagefile", "lines": 2 }, { "name": ".URL url [description] [after]", "lines": 18 }, { "name": ".MTO address [description] [after]", "lines": 14 }, { "name": ".FTP url [description] [after]", "lines": 9 }, { "name": ".TAG name", "lines": 12 }, { "name": ".IMG [-R|-L|-C] filename [width] [height]", "lines": 7 }, { "name": ".PIMG [-R|-L|-C] filename [width [height]]", "lines": 6 }, { "name": ".MPIMG [-R|-L] [-G gap] filename [width [height]]", "lines": 69 }, { "name": ".DC l text [color]", "lines": 9 }, { "name": ".ALN [color] [percentage]", "lines": 16 }, { "name": ".LINKSTYLE color [ fontstyle [ openglyph closeglyph ] ]", "lines": 7 } ] }, { "name": "SECTION HEADING LINKS", "lines": 4, "subsections": [] }, { "name": "LIMITATIONS OF GROHTML", "lines": 2, "subsections": [] }, { "name": "FILES", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 3, "subsections": [] }, { "name": "SEE ALSO", "lines": 5, "subsections": [] } ] } }