[bug #53664] an-old.tmac: .TP causes wrong formatting with a long tag

[G. Branden Robinson]

Update of bug #53664 (project groff):

  Status:   Need Info => Invalid
 Open/Closed:Open => Closed 

___

Follow-up Comment #4:

Thanks, Bjarni.

Closing as invalid; see https://savannah.gnu.org/bugs/index.php?53715 for the
pertinent issue.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53715] [PATCH] pic2graph.1: Use macro 'TP' without an extra (long) indent

[G. Branden Robinson]

Update of bug #53715 (project groff):

Severity:  3 - Normal => 2 - Minor  


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53664] an-old.tmac: .TP causes wrong formatting with a long tag

[Bjarni Ingi Gislason]

Follow-up Comment #3, bug #53664 (project groff):

  I did not need to.

  I blamed the wrong file.

When I saw the warning about "can't break line" from "groff",
I checked the output.
Saw the long tag and what prevailed was a memory,
that when the tag is long,
the next text goes into the next line (with a normal indent),
which was not the case here.
So I blamed the macro, which was wrong.

  The culprit is the long indent.

  I have made a new report, which fixes the indention.
The bug report is nr. 53715 and should be mentioned when this wrong report
is closed.


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53715] [PATCH] pic2graph.1: Use macro 'TP' without an extra (long) indent

[Bjarni Ingi Gislason]

URL:
  

 Summary: [PATCH] pic2graph.1: Use macro 'TP' without an extra
(long) indent
 Project: GNU troff
Submitted by: bjarniig
Submitted on: Sun 22 Apr 2018 01:30:15 AM UTC
Category: None
Severity: 3 - Normal
  Item Group: Documentation
  Status: None
 Privacy: Public
 Assigned to: None
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:


>From 3882790050fe8de32f6c6e8ba26dbe2518d98fc0 Mon Sep 17 00:00:00 2001
From: Bjarni Ingi Gislason 
Date: Sat, 21 Apr 2018 22:47:07 +
Subject: [PATCH] pic2graph.1: Use macro 'TP' without an extra (long) indent

  A long indent wastes space, can cause a "can't break line" warning,
and causes a bad (worse) formatting.

Signed-off-by: Bjarni Ingi Gislason 
---
 contrib/pic2graph/pic2graph.1.man | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/contrib/pic2graph/pic2graph.1.man
b/contrib/pic2graph/pic2graph.1.man
index 784aff5f..42f5ecc6 100644
--- a/contrib/pic2graph/pic2graph.1.man
+++ b/contrib/pic2graph/pic2graph.1.man
@@ -148,7 +148,7 @@ Command-line switches and arguments not listed above are
passed to
 .SH FILES
 .\" 
 .
-.TP \w'\fB@MACRODIR@/eqnrc'u+2n
+.TP
 .B @MACRODIR@/eqnrc
 The
 .BR @g@eqn (@MAN1EXT@)
-- 
2.17.0






___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53547] [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

[G. Branden Robinson]

Follow-up Comment #5, bug #53547 (project groff):

The lack of sufficient context in the diff got me.  The situation is simpler;
it's not a "de-dent", but a normal hanging indent for which we have a standard
English term in typography.  The nonce word is still useful as a mnemonic for
the macro.  I have the following change pending.


@@ -426,7 +426,8 @@ or
 .PP
 The
 .B XP
-macro produces an exdented paragraph.
+macro produces an \(lqexdented\(rq paragraph; that is, one with a
+hanging indent.
 .
 The first line of the paragraph begins at
 the left margin,


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

Re: [groff] groff as the basis for comprehensive documentation?

[G. Branden Robinson]

At 2018-04-21T18:21:28-0400, James K. Lowden wrote:
> On Sat, 21 Apr 2018 12:59:16 -0500
> Nate Bargmann  wrote:
> 
> > But why do we focus on presentation when authoring a document?  
> 
> Because the document we see is what we're creating.  The only purpose
> of the document is to be read, and appearance matters to the reader.
> The reader assuredly doesn't care about semantic markup.  
> 
> Semantic markup is an abstraction that assists the author.  It can
> ensure that semantically similar things -- section headers, quotations,
> etc. -- are rendered consistently.  It can help -- somewhat -- in
> rendering the same input text pleasantly in different output formats.
> It can help indexing programs and such knit together different
> documents in ways that are useful to the user (and thus to the
> author).  
> 
> There's no Higher Good honored by using semantic markup.  It's a tool
> to use if it gets you where you want to go.  Ultimately, though, you
> want your text to be read, and it is altogether fitting and proper that
> you be concerned with its appearance.  

This is true for literature, like poetry or a novel.

For nonfiction, there are additional objectives--full-text searchability
and cross-referencing.  For technical documentation of software systems,
we can further add templating.

By "templating" I mean the little markup-convention languages we use to
distinguish literal text from variable text, and punctuation symbols
like brackes, braces, bars, and ellipses we draft into service to
communicate the regularity (in the formal sense) of the underlying
expressions.

-- 
Regards,
Branden


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[James K. Lowden]

On Sat, 21 Apr 2018 08:16:36 -0500
Nate Bargmann  wrote:

> > For lack of a better term, I think it's an abstraction mismatch.
> > The ditroff language presupposes a dot-addressable canvas, onto
> > which lines and strings of text are drawn.  That model fits most
> > printers (these days) and terminals.  But it doesn't describe HTML
> > at all.  
> 
> I suppose it depends on what one expects from the generated HTML.  As
> one who reads pages more than writes them, I've been impressed with
> the presentation on the man-pages project Web site (hosted at
> kernel.org). For example, here is the rendering of groff_man(7):
> 
> http://man7.org/linux/man-pages/man7/groff_man.7.html
> 
> I couldn't find the generator being used in the Git repository and a
> lot of it may be done with CSS.  The text is rendered using the 
> tag so it looks much like tty output though it is not fully justified
> yet the text blocks are indented.  Aside from the justification, the
> rest looks very familiar to me. 

I find very little to commend that version.  In fact, it's an excellent
example of the widespread dunderheaded monospace manpage rendering on
the web.  I invite you to compare it with something better: 

https://linux.die.net/man/7/groff_man

(Better url, too, btw: "man/7/groff_man" captures everything
"man-pages/man7/groff_man.7.html" does in half the space.)  

(One has to wonder, though, at the age of that document.  For
amusement, follow the link in See Also.)  

There's nothing in the manpage input text that specifies the font family
to be used.  The Postscript rendering uses proportional fonts and
italics, much more pleasant to read than nroff output in a terminal.
Why shouldn't the HTML output make the highest and best use of its
medium, instead of poorly emulating a 40 year-old obsolete hardware?  

> Note that I am only working with Groff's man macro package and do
> understand that other macro packages may have greater demands on the
> HTML generator.

It's not the demands on the HTML *generator* that present the problem.
The input to grohtml is devoid of information HTML itself demands, and
is thick with information it can't use.  

HTML needs: titles, paragraphs, tables
ditroff provides: positions, text, fonts

The only reason it works at all is that the pre-grohtml preprocessor
sneaks some useful information to the postprocessor via ditroff
escapes.  That allows grohtml to generate MathML from eqn output, for
example.  

While it's possible to work that way, I see no advantage to squirting
most of the needed information to the post-processor through the
formatter, when the formatter's work is discarded by the
post-processor.  Why bother?  just translate the macros directly.  

Which, I suppose, it what Ingo is doing already.  

--jkl

Re: [groff] groff as the basis for comprehensive documentation?

[James K. Lowden]

On Sat, 21 Apr 2018 12:59:16 -0500
Nate Bargmann  wrote:

> But why do we focus on presentation when authoring a document?  

Because the document we see is what we're creating.  The only purpose
of the document is to be read, and appearance matters to the reader.
The reader assuredly doesn't care about semantic markup.  

Semantic markup is an abstraction that assists the author.  It can
ensure that semantically similar things -- section headers, quotations,
etc. -- are rendered consistently.  It can help -- somewhat -- in
rendering the same input text pleasantly in different output formats.
It can help indexing programs and such knit together different
documents in ways that are useful to the user (and thus to the
author).  

There's no Higher Good honored by using semantic markup.  It's a tool
to use if it gets you where you want to go.  Ultimately, though, you
want your text to be read, and it is altogether fitting and proper that
you be concerned with its appearance.  

--jkl

[bug #53547] [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

[G. Branden Robinson]

Follow-up Comment #4, bug #53547 (project groff):

It makes sense that where English has 0 standard words for a concept, German
would have two.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

Re: [groff] Savannah bug field usage protocol

[G. Branden Robinson]

At 2018-04-21T14:21:03+0100, Ralph Corderoy wrote:
> Hi,
> 
> Ingo wrote:
> > All of this can and should be disregarded for changes that are so
> > minor that they will definitely never be mentioned in release notes or
> > similar.
> 
> Some projects maintain a `pending' release notes so that significant
> fixes and changes get added to as they're implemented.  This might avoid
> the need to keep some bugs non-closed until the release.  Come release,
> the file's reviewed, some minor things with highsight ditched, and the
> commit log scanned for anything missing.

Our commit discipline is already supposed to include updating the
ChangeLog, and, where appropriate, NEWS files as part of the commit
where the underlying change is made.  Do you think that should suffice
for aiding the preparation of Release Notes?

-- 
Regards,
Branden


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[Steffen Nurpmeso]

Nate Bargmann  wrote:
 |* On 2018 19 Apr 18:47 -0500, James K. Lowden wrote:
 |> On Fri, 20 Apr 2018 01:44:06 +1000
 |> John Gardner  wrote:
  ...
 |I, for one, do not expect an HTML rendered version of *anything* to
 |be a faithful representation of a printed page.  The output of
 |"groff -man -Thtml ..." is reasonable for my purposes, except that I'd
 |like to be able to generate relative links in a page to other pages in
 |my project.  Maybe I just need to do some sed(1) transformation after
 |groff is done.

I have for example

  .   el .ie 'html'\*[.T]' \
  . mx:dump-init-html
[...]
  .de mx:dump-init-html
  . \" grohtml is real shit..
  . mso html.tmac
[get HTML macros]
  . als mx:dump-xr  mx:dump-xr-html
  . als mx:dump-anchor  mx:dump-anchor-html
  . als mx:dump-ref mx:dump-ref-html
  ..
  .
  .de mx:dump-xr-html
  . \" Cannot help it
  ..
  .
  .de mx:dump-anchor-html
  . TAG "\$2"
  . if d mx-debug \
  .   HTML #\$2#
  ..
  .
  .de mx:dump-ref-html
  . URL "#\$1" "[\$1]"
[create an active reference]
  ..

I have to excuse myself for the strong wording.

 |Note that I am only working with Groff's man macro package and do
 |understand that other macro packages may have greater demands on the
 |HTML generator.

I really want to excuse my strong wording.

--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: [groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

* On 2018 21 Apr 09:56 -0500, John Gardner wrote:
> We just need a post-processor that can generate reusable, *stylable* HTML
> output for an endless and unpredictable range of both site layouts and
> portable devices. Intelligently-structured markup is the first step – most
> front-end developers these days are reusing existing stylesheets written in
> a variety of CSS precompilers. The only way to accommodate this
> all-pervasive cesspool of copy+pasta is *to focus on content and semantics,
> not its presentation*.

I like the ambition on display, John.  :-)

Beyond the things you've already outlined and the thing I've mentioned,
I forgot about things like Media-Wiki markup and now the use of Markdown
for Wiki markup (that reads like we're going one way to go the other!)

I've done project documentation in each of those mentioned and had to
convert the Media-Wiki stuff to SourceForge.net's dialect of Wiki
Markdown when they dumped the use of Media-Wiki.  Then earlier this year
SF.net became wholly unreliable so I moved our stuff over to the GitHub
wiki and had to do some editing to make it right there again.

If I were emperor of the universe I would put a moratorium on document
formats!

But why do we focus on presentation when authoring a document?  I think
that in large part we have trained ourselves to do so using the various
desktop word processing/publishing programs that came down the pike.
I've done plenty of documents where the content was subservient to the
presentation (newsletters and such).  A word processor forces a
presentation first mindset because its only real output is the printed
page.  It's not a GUI thing, I was spending as much time tweaking the
presentation in the codes editor in Word Perfect 5.1 on MS-DOS in 1990
as I was writing lab reports.

Working in the presentation mindset for so long makes it difficult to
think in terms of semantic markup.  I'm not sure I really understand it
fully.  Even working with the man macros, I still spend some amount of
time checking the presentation on the terminal and with PDF and HTML
output.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

>
>
>
> *So you’re going to insert devtags to pass semantic info to the
> postprocessor?...Personally, I think you’re going to have better luck
> passing semantic hints through as you mentioned above.*


Sort of. Sticking to pre- and post-processors is really about separation of
concerns more than anything else. There're no assumptions about what macro
packages an author's using, which preprocessors they're using, or even what
fonts they use. As long as Kernighan's output language is what we're
dealing with... game on.

*Any chance you could use an MUA that has a consistent quoting style and
> ties In-Reply-To, References, and the bits being quoted together? Otherwise
> threading for those of us using it suffers.*


Shit, I'm so sorry. =( I'm writing from Gmail (in Chrome), and applying
formatting manually. This  is what I'm
looking at right now...

I keep forgetting how this must look to users of other mail clients... :(


On 22 April 2018 at 01:06, Larry Kollar  wrote:

> Some of this is really cool, and ties in with a couple things I’ve tried
> in the past.
>
> John Gardner  wrote:
>
> > *1. Handling semantics*
> > We all know you can't draw semantics from cold, low-level formatting
> > commands. But for certain contexts - hierarchically sorted documents,
> > consistently indented code-samples and tables marked as tables, I believe
> > (okay, *hoping)* it's possible to reconstruct meaning from... well, stuff
> > that looks like this:
> >
> > n12000 0 V84000 H72000
> > x X devtag:.NH 1
> > x font 36 TB
> > f36s10950V84000H72000
> >
> > How? See the x X devtag line? That's what inspired this whole landslide
> of
> > absurd ambition. I wondered what we could do if more metadata were
> provided
> > that way – as device-specific control strings from, say, a preprocessor.
>
> So you’re going to insert devtags to pass semantic info to the
> postprocessor?
> Cool idea. I wrote a script called “htbl” some years back to go with
> grothml; it
> turns a subset of tbl markup into HTML tables. I never thought of using
> devtags
> to mark rows/cells like that; it might have worked better.
>
> > ...
> >
> > We know the widths and heights of each mounted device-font, their
> > kerning-pairs, ligatures, and lord knows what else. We milk this for all
> > it's worth: by plotting each glyph's bounding box in a scaled space
> > representing the output medium, we identify the most obvious constructs
> > first.
>
> That’s pretty similar to the PDF-to-markup thing I blithered about earlier.
> I think a more skilled programmer than myself (I’m a jumped up tech writer)
> could really make it work well… although as i said before, each document
> is unique. Personally, I think you’re going to have better luck passing
> semantic
> hints through as you mentioned above. But it does sound like fun! I hope
> you
> keep us posted.
>
> Larry
>
>
>

Re: [groff] groff as the basis for comprehensive documentation?

[Ralph Corderoy]

Hi John,

> >
> >

> * *

Any chance you could use an MUA that has a consistent quoting style and
ties In-Reply-To, References, and the bits being quoted together?
Otherwise threading for those of us using it suffers.
I realise it may mean two or three short replies when one summary would
do, but most of the time the extra noise is at an accepted level.

> Somedays I'll write `e-mail`, and other days it just looks like I'm
> subtracting the value of the `mail` variable

Teach your spelling checker right from wrong?  :-)

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy

Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

>
> *I, for one, do not expect an HTML rendered version of *anything* to be a
> faithful representation of a printed page.*


Barring physical factors like paper size, overprint, bleed and other
print-specific stuff, it's actually possible – thanks to CSS. It can
declaratively target 3 very different output mediums
:
screen (browsers, tablets, phones, projectors, etc), print, and speech (the
last medium is particularly crippled by poorly structured markup...) There
were originally others, but they were axed from the spec largely due to the
shift in the technology landscape. Having tv, projection, and handheld as
distinct media types made less sense as smartphones took off and browsers
went mobile. Others like braille and embossed were narrow attempts at
accessibility - WHATWG realised that disabilities and assistive
technologies were too complex to be addressed by CSS alone, so it was
deferred to WAI-ARIA instead...

On 22 April 2018 at 00:54, John Gardner  wrote:

> None of those, and certainly not an em dash. It's `man page', short for
>> `manual pages'.
>
>
> Haha, don't worry! =) I was being facetious. Probably could've
> communicated the joke better with `man\D'l 99n 0'pages` instead.
>
> In all seriousness, I can be horribly inconsistent with hyphenation in
> general, and I drive myself nuts. Somedays I'll write `e-mail`, and other
> days it just looks like I'm subtracting the value of the `mail` variable
> from whatever value is bound to `e` =(
>
> *I suppose it depends on what one expects from the generated HTML.*
>
>
> I should probably explain my other motive for developing these
> post-processors. Schooling Ingo on HTML earlier has probably left me
> looking way more critical and judgemental of people's markup than I really
> am. It's arrogance and ignorance (and too much holding-my-tongue) that
> caused me the long-winded bitchslap I gave before.
>
> As I mentioned earlier, I recently refactored Node.js's manpage to use
> mdoc(7) macros instead of man(7). My motive was to make formatting errors
> harder for the majority of contributors, most of whom are unfamiliar with
> roff or its macros. I was checking Node.js's repository to see if a patch
> for OpenBSD had landed, and saw a recent commit
> 
> titled *"doc: fix manpage warnings"*.  (Keep in mind this is the *only*
> Roff file in a sea of markdown files. Heck, the project's *canonical
> source* of documentation are markdown files split, parsed, and fed
> through a variety of interlocked JavaScript modules to produce parsable
> output suitable for their site's API pages
> .
>
> An attempt  was made to do the
> same for generating manpages, but the contributor couldn't find the time to
> finish the PR. I'd assumed it may have had something to do with lack of
> Roff-knowledge, rather than the fact he was using Node.js's JSON-formatted
> docs to generate the manpages. After all, anything in JSON format is
> *surely* done with the intent of making content portable and
> not-at-all-format specific, right? Right? I *OH GOD, IS THAT RAW HTML
> IN JSON THAT WAS GENERATED FROM MARKDOWN?! *
>
> Yes. Yes it is. *And the entire web industry can't stop doing this shit.*
>
> The web industry's obsession with markdown is going too far. Honestly, I
> get the appeal of markdown being contributor-friendly, but when you've got
> 30-odd dependencies to generate JSON, static HTML, PDF and
> god-knows-what-else, and you're *still* tasked with checking a manpage to
> see if its options are "in sync with the rest of the documentation", you
> can't help but wonder where the hell everybody went wrong.
>
> Troff is a powerful, horribly under-appreciated system. If people actually
> bothered to write manpages by hand, they'd be amazed by what the language
> and its associated programs can really do. But today's generation of devs
> have zero incentive to even give it a try. Those who are impelled to learn
> any sort of programmatic document preparation will default to LaTeX,
> period. Even if compiling LaTeX documents is as pleasant as pulling teeth,
> and even if LaTeX formats are binary and completely opaque to the casual
> observer.
>
> *The only sane response to insanity is more insanity, *and I'm probably
> crazy enough to believe more devs might give Roff a crack if they knew it
> was easier to generate markdown and HTML from Roff, rather than the other
> way around. Trouble is, grohtml's HTML output is, uh, somewhat archaic in
> the age when HTML5 is now considered an umbrella family of specifications
> , rather than a language revision.
> Now, I'm not holding this against anybody - when grohtml was 

Re: [groff] groff as the basis for comprehensive documentation?

[Larry Kollar]

Some of this is really cool, and ties in with a couple things I’ve tried in the 
past.

John Gardner  wrote:

> *1. Handling semantics*
> We all know you can't draw semantics from cold, low-level formatting
> commands. But for certain contexts - hierarchically sorted documents,
> consistently indented code-samples and tables marked as tables, I believe
> (okay, *hoping)* it's possible to reconstruct meaning from... well, stuff
> that looks like this:
> 
> n12000 0 V84000 H72000
> x X devtag:.NH 1
> x font 36 TB
> f36s10950V84000H72000
> 
> How? See the x X devtag line? That's what inspired this whole landslide of
> absurd ambition. I wondered what we could do if more metadata were provided
> that way – as device-specific control strings from, say, a preprocessor.

So you’re going to insert devtags to pass semantic info to the postprocessor?
Cool idea. I wrote a script called “htbl” some years back to go with grothml; it
turns a subset of tbl markup into HTML tables. I never thought of using devtags
to mark rows/cells like that; it might have worked better.

> ...
> 
> We know the widths and heights of each mounted device-font, their
> kerning-pairs, ligatures, and lord knows what else. We milk this for all
> it's worth: by plotting each glyph's bounding box in a scaled space
> representing the output medium, we identify the most obvious constructs
> first.

That’s pretty similar to the PDF-to-markup thing I blithered about earlier.
I think a more skilled programmer than myself (I’m a jumped up tech writer)
could really make it work well… although as i said before, each document
is unique. Personally, I think you’re going to have better luck passing semantic
hints through as you mentioned above. But it does sound like fun! I hope you
keep us posted.

Larry

Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

>
> None of those, and certainly not an em dash. It's `man page', short for
> `manual pages'.


Haha, don't worry! =) I was being facetious. Probably could've communicated
the joke better with `man\D'l 99n 0'pages` instead.

In all seriousness, I can be horribly inconsistent with hyphenation in
general, and I drive myself nuts. Somedays I'll write `e-mail`, and other
days it just looks like I'm subtracting the value of the `mail` variable
from whatever value is bound to `e` =(

*I suppose it depends on what one expects from the generated HTML.*


I should probably explain my other motive for developing these
post-processors. Schooling Ingo on HTML earlier has probably left me
looking way more critical and judgemental of people's markup than I really
am. It's arrogance and ignorance (and too much holding-my-tongue) that
caused me the long-winded bitchslap I gave before.

As I mentioned earlier, I recently refactored Node.js's manpage to use
mdoc(7) macros instead of man(7). My motive was to make formatting errors
harder for the majority of contributors, most of whom are unfamiliar with
roff or its macros. I was checking Node.js's repository to see if a patch
for OpenBSD had landed, and saw a recent commit

titled *"doc: fix manpage warnings"*.  (Keep in mind this is the *only*
Roff file in a sea of markdown files. Heck, the project's *canonical source* of
documentation are markdown files split, parsed, and fed through a variety
of interlocked JavaScript modules to produce parsable output suitable for
their site's API pages .

An attempt  was made to do the
same for generating manpages, but the contributor couldn't find the time to
finish the PR. I'd assumed it may have had something to do with lack of
Roff-knowledge, rather than the fact he was using Node.js's JSON-formatted
docs to generate the manpages. After all, anything in JSON format is
*surely* done with the intent of making content portable and
not-at-all-format specific, right? Right? I *OH GOD, IS THAT RAW HTML
IN JSON THAT WAS GENERATED FROM MARKDOWN?! *

Yes. Yes it is. *And the entire web industry can't stop doing this shit.*

The web industry's obsession with markdown is going too far. Honestly, I
get the appeal of markdown being contributor-friendly, but when you've got
30-odd dependencies to generate JSON, static HTML, PDF and
god-knows-what-else, and you're *still* tasked with checking a manpage to
see if its options are "in sync with the rest of the documentation", you
can't help but wonder where the hell everybody went wrong.

Troff is a powerful, horribly under-appreciated system. If people actually
bothered to write manpages by hand, they'd be amazed by what the language
and its associated programs can really do. But today's generation of devs
have zero incentive to even give it a try. Those who are impelled to learn
any sort of programmatic document preparation will default to LaTeX,
period. Even if compiling LaTeX documents is as pleasant as pulling teeth,
and even if LaTeX formats are binary and completely opaque to the casual
observer.

*The only sane response to insanity is more insanity, *and I'm probably
crazy enough to believe more devs might give Roff a crack if they knew it
was easier to generate markdown and HTML from Roff, rather than the other
way around. Trouble is, grohtml's HTML output is, uh, somewhat archaic in
the age when HTML5 is now considered an umbrella family of specifications
, rather than a language revision. Now,
I'm not holding this against anybody - when grohtml was devised, it was...
what, early 2001? 2002? CSS support was spotty and inconsistent, and the W3
kept claiming XML/XHTML was the way of the future. Zero progress was made
for about 7 years, and I honestly can't blame Groff for using very outdated
layout techniques. Basically, anything laid out using HTML tables clearly
wasn't written within the last decade...

We just need a post-processor that can generate reusable, *stylable* HTML
output for an endless and unpredictable range of both site layouts and
portable devices. Intelligently-structured markup is the first step – most
front-end developers these days are reusing existing stylesheets written in
a variety of CSS precompilers. The only way to accommodate this
all-pervasive cesspool of copy+pasta is *to focus on content and semantics,
not its presentation*.



On 21 April 2018 at 23:25, Ralph Corderoy  wrote:

> Hi John,
>
> > Manpages, man-pages, or man\(empages?
>
> None of those, and certainly not an em dash.
> It's `man page', short for `manual pages'.
>
> $ dict -ms regexp 'man.*page'
> jargon:  "man page"
> foldoc:  "demand paged"  "man page"  "unix man page"
>   "unix manual page"
>   

Re: [groff] groff as the basis for comprehensive documentation?

[Larry Kollar]

John Gardner  wrote:

> It's ironic how this convention of unconventional formatting has stuck
> around since the beginning, but in over 40 years of writing manpages,
> nobody's been able to agree on a consistent way of hyphenating the damn
> word.
> 
> Manpages, man-pages, or man\(empages?

I’ve always made it a compound word, “manpages.” And I’m in violent agreement
with your and Brandon’s assessment of all-caps headings. Shoot, there aren’t 
many
terminal programs that *can’t* do bold these days; I think even that VT220 I 
keep
planning to connect to my iMac can do it.

Given a choice, I never all-caps my manpage headings. I’ve succumbed to 
convention
once or twice, maybe. It would be cool if man(1) could recognize an all-caps 
string
flush left, and turn it into bolded title case.

Larry

[bug #53547] [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

[Werner LEMBERG]

Follow-up Comment #3, bug #53547 (project groff):

In German, there are actually two words for that: `einrücken' und
`ausrücken'. :-)

I suggest to add an explanation in parentheses in case native English speakers
don't understand `exdent'.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

Re: [groff] groff as the basis for comprehensive documentation?

[Ralph Corderoy]

Hi John,

> Manpages, man-pages, or man\(empages?

None of those, and certainly not an em dash.
It's `man page', short for `manual pages'.

$ dict -ms regexp 'man.*page'
jargon:  "man page"
foldoc:  "demand paged"  "man page"  "unix man page"
  "unix manual page"
$

It might get hyphenated as a compound adjective, `the man-page macros',
or in a filename where as space isn't wanted, `man-pages.7'.

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy

Re: [groff] Savannah bug field usage protocol

[Ralph Corderoy]

Hi,

Ingo wrote:
> All of this can and should be disregarded for changes that are so
> minor that they will definitely never be mentioned in release notes or
> similar.

Some projects maintain a `pending' release notes so that significant
fixes and changes get added to as they're implemented.  This might avoid
the need to keep some bugs non-closed until the release.  Come release,
the file's reviewed, some minor things with highsight ditched, and the
commit log scanned for anything missing.

-- 
Cheers, Ralph.
https://plus.google.com/+RalphCorderoy

Re: [groff] groff as the basis for comprehensive documentation?

[Nate Bargmann]

* On 2018 19 Apr 18:47 -0500, James K. Lowden wrote:
> On Fri, 20 Apr 2018 01:44:06 +1000
> John Gardner  wrote:
> 
> > > You might like to believe that eqn, tbl, and pic could be processed
> > > with grohtml
> > 
> > I've seen grohtml's complexity and was bewildered.  Hence why I
> > intend to write my own. The procedures for inferring structural or
> > semantic metadata from low-level intermediate output commands will be
> > an entertaining challenge. =)
> 
> For lack of a better term, I think it's an abstraction mismatch.  The
> ditroff language presupposes a dot-addressable canvas, onto which lines
> and strings of text are drawn.  That model fits most printers (these
> days) and terminals.  But it doesn't describe HTML at all.  
> 
> I discussed HTML output with Ted Faber, of grap, upon a time.  He
> produces HTML from a handful of his own macros.  ISTM ms macros map
> onto HTML pretty well:
> 
>   .SH => 
>   .PP => 
>   .I  => 
>   .B  => 
> 
> and so on.  But what, for example, is HTML to do with line
> justification, and why should the browser honor the (implied) line
> breaks, when it has its own line-wrapping logic and style sheet, and
> the page size is dynamic?

I suppose it depends on what one expects from the generated HTML.  As
one who reads pages more than writes them, I've been impressed with the
presentation on the man-pages project Web site (hosted at kernel.org).
For example, here is the rendering of groff_man(7):

http://man7.org/linux/man-pages/man7/groff_man.7.html

I couldn't find the generator being used in the Git repository and a lot
of it may be done with CSS.  The text is rendered using the  tag so
it looks much like tty output though it is not fully justified yet the
text blocks are indented.  Aside from the justification, the rest looks
very familiar to me.  Links to other hosted man pages are present.

I, for one, do not expect an HTML rendered version of *anything* to
be a faithful representation of a printed page.  The output of
"groff -man -Thtml ..." is reasonable for my purposes, except that I'd
like to be able to generate relative links in a page to other pages in
my project.  Maybe I just need to do some sed(1) transformation after
groff is done.

Note that I am only working with Groff's man macro package and do
understand that other macro packages may have greater demands on the
HTML generator.

- Nate

-- 

"The optimist proclaims that we live in the best of all
possible worlds.  The pessimist fears this is true."

Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

*> The section heading examples in man-pages(7) are in all upper case.*

It's ironic how this convention of unconventional formatting has stuck
around since the beginning, but in over 40 years of writing manpages,
nobody's been able to agree on a consistent way of hyphenating the damn
word.

Manpages, man-pages, or man\(empages?

On 21 April 2018 at 22:16, Nate Bargmann  wrote:

> * On 2018 21 Apr 02:07 -0500, G. Branden Robinson wrote:
> > In my opinion, which I am far too young and poorly-connected to have
> > proffered when it would have made any difference, the
> > forced-full-capitalization of section titles in man page sources is an
> > information-destroying transform done in the wrong place at the wrong
> > time.  Section headings should be capitalized as section titles normally
> > are in technical documentation: either like work titles, or first-letter
> > only, with the normal rules for proper nouns and adjectives respected.
>
> To be effective, I think one needs to get Michael Kerrisk of the
> man-pages project https://www.kernel.org/doc/man-pages/ on board.  The
> section heading examples in man-pages(7) are in all upper case.  I've
> been using this page and others of the project along with groff_man(7)
> as a guide for formatting my own pages.
>
> > This has been itching me for many years; thanks for the excuse to air
> > my grievance.  ;-)
>
> Glad to start the thread that has led a number of different directions!
> :-D
>
> - Nate
>
> --
>
> "The optimist proclaims that we live in the best of all
> possible worlds.  The pessimist fears this is true."
>
> Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB
>

Re: [groff] Savannah bug field usage protocol

[Ingo Schwarze]

Hi Branden,

that all sounds very reasonable to me, for actual bugs.

I'd only suggest one additional simplification:

All of this can and should be disregarded for changes that are so
minor that they will definitely never be mentioned in release notes
or similar.  That is certainly the case for anything so minor that
it doesn't warrant a ChangeLog entry, but i think it also applies
to trivial changes that, for whatever reason, do have a ChangeLog
entry.

For such trivial tickets, figuring out whether the typo (or whatever
it is) was present in a release, setting the "Planned Release"
field, keeping them open, and revisiting them later looks like
a waste of time and effort to me and besides clutters the bug
list.

For example, i think that the following trivial tickets ought to
be closed right away:

  27422 50990 51071 51076 51078 51417 51426 51482 51483 51502
  51513 51540 51541 51888 51598 51609 51610 51611 51695 52333
  52335 52374 52442 52444 52458 52462

That is all stuff you definitely *never* want to look at again,
under no circumstances, and it makes it hard to see actual bugs
that have been fixed.

Of course, it is a matter of taste where exactly to draw the
line between "trivial, get this out of my sight" and "bug fixed,
may be relevant for release notes", and absolute consistency is
neither possible nor required, but the groff bugtracker is so
noisy that i think getting rid of the worst trivialities would
be beneficial.

Yours,
  Ingo


G. Branden Robinson wrote on Sat, Apr 21, 2018 at 06:58:51AM -0400:

> As far as I know, there is no documentation about how we're supposed to
> be using the Open/Closed and Planned Release fields in Savannah.
> 
> Ingo closes bugs whose status he sets to Invalid, but that's not the
> case I'm interested in.
> 
> I'd like to propose that:
> 
> 1. A Fixed bug be Closed immediately[1] if it was only ever extant in
> git, and not in an actual release (not counting release candidates).
> 
> 2. The Planned Release field be used and set to the forthcoming release
> for Fixed bugs that were extant in the most recent actual release.
> 
> 3. That the Owner of a Fixed bug in a Planned Release Close the bug when
> that Planned Release is actually released.
> 
> My rationales are:
> 
> A. I am owner of a bunch of fixed groff bugs in Savannah and I'd like to
> tidy them up in some respect.
> 
> B. From repeated personal negative experiences, I have come to hate it
> when a project slams a bug closed as soon as a commit fixing it is made,
> no matter how many months or years may pass before a release is made.
> If the bug exists in the latest release version of a software project,
> that bug should be easy to find.  This also helps prevent the filing of
> duplicate reports.
> 
> C. This keeps the cost of experimentation low on git HEAD.  There's no
> reason to wear our (my[2]) shame on the bug tracker for screwups that
> never made it into an actual release.  Getting yelled at on the mailing
> list is a good enough deterrent.
> 
> Thoughts?
> 
> [1] Meaning: as soon as the commit is pushed, or reasonably soon
> thereafter, or as soon as someone notices this is the case.
> 
> [2] :)

[bug #53547] [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

[G. Branden Robinson]

Follow-up Comment #2, bug #53547 (project groff):


-macro produces an exdented paragraph.
+macro produces an extended paragraph.


The above change is spurious.  "Exdented" is a nonce word indicating a
negative indent, or left indent.  Some people use the term "dedented" for
this.  As far as I know there is no standard term.

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53547] [PATCH] tmac/groff_ms.7.man: Change bold '[' and ']' to roman and other tidying

[G. Branden Robinson]

Update of bug #53547 (project groff):

  Status:None => In Progress

___

Follow-up Comment #1:

I concur with the following classes of change:

1. Change - to \- if it means a minus sign.

2. Use a macro to change to the italic font, instead of \fI [1], if possible. 
The macros have the italic corrections, but "\c" removes them or add the
italic corrections.

3. Add a comma before "and", "or", or "nor" if a series contains three or more
words. [In other words, use the Oxford comma.]

4. Change '[' and ']' from bold to roman. [In command synopses, yes--only
literals should be rendered in bold.]

I do not concur with the following class of change:

5. Surround a block of comments with the macros ".ig" and "..".  [In my
opinion, the groff man pages should become exemplars of good man page style,
and while .ig and .. are not much harder to understand than "#if 0" and a
corresponding "#endif", that little bit makes a difference.  Comment leaders
are nearly universal in programming languages, and require only a finite
automaton to parse, instead of a pushdown automaton or worse.  I've taught my
Vim installation how to recognize *roff comments, so even reflowing text is no
longer a problem for me.]

Changes I'm still evaluating:

6. Arguments to the macro ".TP" (uses '.itc') [We went back and forth a whole
lot in this, didn't we?]

7. Use '\!' and '\c' to use two input lines as a one line of arguments. [I
need to brush up on \# vs. \! and the interaction each has with \c.]

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53664] an-old.tmac: .TP causes wrong formatting with a long tag

[G. Branden Robinson]

Follow-up Comment #2, bug #53664 (project groff):

Bjarni,

I can't reproduce this on git HEAD.  Bertrand changed @MACRODIR@ and similar
autoconf variables to use SHORT_VERSION instead of AC_PACKAGE_VERSION.  On my
system, that seems to help with the absurdly long paragraph tags when an
installed groff filespec is the tag.

Can you still reproduce this?

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53673] [PATCH] configure.ac: Correct spelling of "striped"

[G. Branden Robinson]

Update of bug #53673 (project groff):

  Status: In Progress => Fixed  
 Open/Closed:Open => Closed 


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[groff] 01/01: configure.ac: Fix typo in comment.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit c549b637a7002337cfa413b4eda7c3dfca8fc4a7
Author: G. Branden Robinson 
Date:   Sat Apr 21 07:10:20 2018 -0400

configure.ac: Fix typo in comment.

Thanks to Bjarni Ingli Gislason for catching this.  It is, after all, an
autoconf script, not a bass script.

Fixes bug https://savannah.gnu.org/bugs/?53673.

Signed-off-by: Bjarni Ingi Gislason 
Signed-off-by: G. Branden Robinson 
---
 configure.ac | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/configure.ac b/configure.ac
index 152ac91..ff89f11 100644
--- a/configure.ac
+++ b/configure.ac
@@ -25,7 +25,7 @@ AC_INIT([GNU Troff],
 
 AC_PREREQ([2.62])
 
-# Version consisting of exactly MAJOR.MINOR.PATCH, striped of any
+# Version consisting of exactly MAJOR.MINOR.PATCH, stripped of any
 # digit after PATCH.
 AC_SUBST([SHORT_VERSION],
m4_bregexp(AC_PACKAGE_VERSION,[^\(\w+\.\w+\.\w+\).*$],[\1]))

___
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit

[bug #53673] [PATCH] configure.ac: Correct spelling of "striped"

[G. Branden Robinson]

Update of bug #53673 (project groff):

Severity:  3 - Normal => 2 - Minor  


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[bug #53673] [PATCH] configure.ac: Correct spelling of "striped"

[G. Branden Robinson]

Update of bug #53673 (project groff):

  Status:None => In Progress
 Assigned to:None => gbranden   


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[groff] Savannah bug field usage protocol

[G. Branden Robinson]

As far as I know, there is no documentation about how we're supposed to
be using the Open/Closed and Planned Release fields in Savannah.

Ingo closes bugs whose status he sets to Invalid, but that's not the
case I'm interested in.

I'd like to propose that:

1. A Fixed bug be Closed immediately[1] if it was only ever extant in
git, and not in an actual release (not counting release candidates).

2. The Planned Release field be used and set to the forthcoming release
for Fixed bugs that were extant in the most recent actual release.

3. That the Owner of a Fixed bug in a Planned Release Close the bug when
that Planned Release is actually released.

My rationales are:

A. I am owner of a bunch of fixed groff bugs in Savannah and I'd like to
tidy them up in some respect.

B. From repeated personal negative experiences, I have come to hate it
when a project slams a bug closed as soon as a commit fixing it is made,
no matter how many months or years may pass before a release is made.
If the bug exists in the latest release version of a software project,
that bug should be easy to find.  This also helps prevent the filing of
duplicate reports.

C. This keeps the cost of experimentation low on git HEAD.  There's no
reason to wear our (my[2]) shame on the bug tracker for screwups that
never made it into an actual release.  Getting yelled at on the mailing
list is a good enough deterrent.

Thoughts?

[1] Meaning: as soon as the commit is pushed, or reasonably soon
thereafter, or as soon as someone notices this is the case.

[2] :)

-- 
Regards,
Branden


signature.asc
Description: PGP signature

[bug #53316] src/devices/grolj4/lj4_font.5.man: spews warning

[G. Branden Robinson]

Update of bug #53316 (project groff):

  Status: In Progress => Fixed  


___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

[groff] 01/01: lj4_font(5): Fix warning.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 056ad3edaa51d120939dea2755119ca9d5e26985
Author: G. Branden Robinson 
Date:   Sat Apr 21 06:35:32 2018 -0400

lj4_font(5): Fix warning.

Fix unquoted escape in eqn input by just not using eqn for this fairly
trivial markup.  Consequently, remove eqn preprocessor hint to man.

Introduced by me in a4f9b86065c02f6b2f385c85526a175ab13ae361,
2017-11-20.  Thanks to Colin Watson for catching this, and to him and
Bjarni Ingli Gislason for the feedback.

Fixes bug https://savannah.gnu.org/bugs/?53316.

Signed-off-by: G. Branden Robinson 
---
 src/devices/grolj4/lj4_font.5.man | 5 +
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/devices/grolj4/lj4_font.5.man 
b/src/devices/grolj4/lj4_font.5.man
index 6e4cf51..7f8e50a 100644
--- a/src/devices/grolj4/lj4_font.5.man
+++ b/src/devices/grolj4/lj4_font.5.man
@@ -1,4 +1,3 @@
-'\" e
 .TH LJ4_FONT @MAN5EXT@ "@MDATE@" "Groff Version @VERSION@"
 .SH NAME
 lj4_font \- groff fonts for use with devlj4
@@ -118,9 +117,7 @@ or any combination
 (e.g.,
 2400 and 3175)
 for which
-.EQ
-res\~\[mu]\~unitwidth = 7\|620\|000.
-.EN
+.IR res \~\[tmu]\~ unitwidth \~=\~7\|620\|000.
 .
 Although HP PCL\~5 LaserJet printers support an internal resolution of
 7200 units per inch,

___
Groff-commit mailing list
Groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit

[bug #53660] bug tracker: Sorting severity fails with "Unknown column 'bugs.bug_id'"

[G. Branden Robinson]

Follow-up Comment #2, bug #53660 (project groff):

Ingo, could you provide a link to {a,the} relevant Savannah Administration
ticket?

I searched for "sort error", and turned up only this one, which was "closed
due to inactivity".

https://savannah.gnu.org/task/?func=detailitem_id=12764

___

Reply to this item at:

  

___
  Message sent via/by Savannah
  http://savannah.gnu.org/


___
bug-groff mailing list
bug-groff@gnu.org
https://lists.gnu.org/mailman/listinfo/bug-groff

Re: [groff] groff as the basis for comprehensive documentation?

[G. Branden Robinson]

At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote:
> >> man://mandoc.1#EXIT_STATUS
> 
> > Now, as for the SHOUTY SHOUTY...
> 
> That's not a matter of SHOUTING, but of case sensitivity.
> The name of that standard section in man(7) and mdoc(7)
> is "EXIT STATUS", not "Exit Status" nor "Exit status"
> nor "exit status".  Case is preserved, consider:

> That's a bad idea.  I admit that many authors use unusual and even
> inconsistent casing in section headers (even in the very mandoc.1)-:,
> which may sometimes seem awkward.  But in technical documentation,
> casing is often deliberate, and automatically changing it based on
> natural language rules is prone to make information incorrect in
> some cases.

I disagree with most of this analysis.  As far as I can tell this was a
presentational decision, similar to the one that led to the Unix
trademark being shown in small caps.  I don't recall the reference but
the reason was not because Unix was supposed to be in full caps--it's
not an acronym, after all--but just to show off a fancy font on the
typesetter.

In my opinion, which I am far too young and poorly-connected to have
proffered when it would have made any difference, the
forced-full-capitalization of section titles in man page sources is an
information-destroying transform done in the wrong place at the wrong
time.  Section headings should be capitalized as section titles normally
are in technical documentation: either like work titles, or first-letter
only, with the normal rules for proper nouns and adjectives respected.

It would be better if man-db (or similar) set a *roff variable
that the macro package would check to see if case transformation on
section headings was desired.  The default, for the next n years, of
course, would be to go ahead and do the transformation to avoid shocking
people.

This has been itching me for many years; thanks for the excuse to air
my grievance.  ;-)

-- 
Regards,
Branden


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[G. Branden Robinson]

At 2018-04-17T00:05:59+1000, John Gardner wrote:
> I'm referring to a select choice of words that just happens to neatly fall
> against the 72-character limit... =) Here's the commit message I was
> referring to:
> 
> Like man(7), mdoc(7) is a macro package for marking up computer manuals.
> The main difference is that mdoc is semantic rather than presentational,
> providing authors with a full DSL to abstract page markup from low-level
> Roff commands. By contrast, `man` is minimalist and leaves formatting to
> the author, who is expected to have a working amount of Roff knowledge.
> 
> Therefore the use of `mdoc` for marking up Node's manpage is a decidedly
> better choice than bare `man`. Less room is left for error and mandoc(1)
> offers very robust error-checking and linting.
> 
> I've been writing every commit-message like this for years and I got too
> good at it, now I look completely mental... :-\

Years ago, we Debian people noticed that our comrade Joey Hess bore a
talent for doing this in ordinary email list traffic.  Hasty research
was done and evidently the term for this is "bricktext".  Some people
have a natural talent for it.  I am not one of them.  :)

-- 
Regards,
Branden


signature.asc
Description: PGP signature

Re: [groff] groff as the basis for comprehensive documentation?

[John Gardner]

Apologies for the out-of-sync response: Ingo's e-mail was binned as spam by
Gmail. Apologies if it sounded like I was ignoring you. =) (I was wondering
where Ralph drew this from:


> *The name of that standard section in man(7) and mdoc(7) is "EXIT**STATUS",
> not "Exit Status" nor "Exit status" nor "exit status".*


Now then. This is gonna be great.


> *Oops, you are rolling your own CSS from scratch.*


Ingo, I've spent the last 13 years in front-end web development, and I've
been writing standards-compliant websites for almost a decade. You are in
absolutely *no* position to be lecturing me on CSS, especially not when
your own is a pigsty.

*I see absolutely nothing semantic in there, it looks like a
> purely presentational style sheet to me.*


... yes, that's the entire reason CSS exists: to separate presentation from
content (the latter being tantamount with "semantics" as understood by web
authors and those of us who actively follow modern web standards). Whatever
your interpretation of "semantic" is, it's firmly-entrenched in some
mdoc-centric little realm far removed from the web platform.

*Are you aware of this semantic style sheet for manual pages:*


The stylesheet is atrocious, and only "semantic" insofar as direct
likenesses to mdoc markup is concerned. Probably looks adequate to systems
programmers, but to a web developer, it more resembles the auto-generated
slop Microsoft Office generated in the old days when saving Word documents
as HTML.

*With HTML code containing the correct attributes*


Correct? You've managed to get *everything* wrong. HTML and CSS is *NOT* mdoc,
yet you write it as such and then brag frequently about mandoc's "superior
HTML output". I've had enough.

*Shortlist of what mandoc fucks up with HTML:*

   1.
*Redundant title attributes on everything. *Actually, worse than redundant:
   it screws with assistive technologies like screen-readers, which might read
   the contents of a tag to the user using the title attribute if one is
   present. If you want to attach page or application-specific metadata to
   elements, use data-*
   
   instead.


   -
*Presentational tags used instead of those conveying text-level
semantics: *You're
   literally doing what mdoc(7) tells you not to do, except in HTML form:
  - -b, -S, -o:
  Flags/options should be represented using kbd tags, as they describe user
  input .
  - =*option*:
  Parameters should use var tags to indicate a placeholder name for an
  expectant value
  - Use dfn to markup the defining subject's name. For mdoc, this means
  *Nm*
   - *Inconsistent or incorrect use of sectioning elements*
   You linked to https://man.openbsd.org/gcc.1 as an example. CTRL+F and
   search for "Options Controlling the Kind of Output".
   I'd hotlink the section directly, but you neglected to use an ID
   attribute or even an anchor element with a name attribute. Did you mean to
   use all those separate  tags as an indication of quality output, or was
   that an oversight?
   - *Pointless empty elements everywhere*
   - *Class attributes assigned to elements which should be styled using
   SIMPLE stylesheet declarations*

Also, half of your "semantic stylesheet "
is redundant and repeating default properties. Many values aren't actually
doing anything, and several rulesets are empty altogether.

I can't go on. I'm feeling queasy with fremdschämen. Seriously.


On 21 April 2018 at 07:19, Ingo Schwarze  wrote:

> Hi John,
>
> John Gardner wrote on Sat, Apr 21, 2018 at 06:21:33AM +1000:
> > Ingo Schwarze wrote:
>
> >> and blanks in fragment names replaced by underscores rather than
> >> hyphens, for example:
>
> > The underscores look really jarring...
> > what's the argument against using dashes instead?
>
>$ man -k Sh,Ss=- | wc -l
> 43
>$ man -k Sh,Ss=_ | wc -l
> 11
>
> Dashes are much more common in normal English text (which section
> and subsection headings usually consist of).  If you see a hyphen
> there, you expect that it represents a hyphen, right?  Besides,
> i regard the underscore as the ASCII printable character most
> visually similar to the blank as it draws nothing *inside* the
> box, but just at the edge.
>
> But really, it's no big deal, i could have gone with the hyphen
> back then, but nobody said they would prefer it when the decision
> was made.  I'm merely pointing out there is an opportunity here to
> consciously choose to be compatible, or to not be compatible...  :)
>
> >> man://mandoc.1#EXIT_STATUS
>
> > Now, as for the SHOUTY SHOUTY...
>
> That's not a matter of SHOUTING, but of case sensitivity.
> The name of that standard section in man(7) and mdoc(7)
> is "EXIT STATUS", not "Exit Status" nor "Exit status"
> nor "exit status".  Case is preserved, consider:
>
>