Re: [groff] Now online: gropdf / grops previewer

[John Gardner]

Hey Branden,

> I'd love to see what the source looks like, but when I alter the URL, I
> get a bunch of 404s.

Everything is on GitHub . The
browser-friendly version is on a separate branch
, as I had to do a few
hacks to address the dependencies on an Electron/Node.js environment.

However, the code for panning and zooming was made a separate project
. Achieving the effect in a
browser-efficient manner was oddly involved, and it felt too heavyweight to
lump in with the rest of the Roff-specific work. The code works, I just
realised I need to clamp it to a certain range.

Trouble is, that range will vary. Zooming won't always be smack in the
dead-centre, either. While not implemented in the web-demo, there will be a
"double-click to zoom in" functionality that should logically centre on
wherever the user clicked.

Complicating matters further is the fact the window pane's width will vary
depending on how wide the user's scaled it, and the fact that manually
setting scroll offsets to compensate for zooming causes a visible "jolt"
because they happen on different redraws... I may have to implement
scrolling manually.

I found a possible Unicode handling problem. In the attached ditroff
> output, note that the angle brackets around the email address in the
> "AUTHORS" section are rendered as different glyphs altogether.


I'm seeing angle brackets: ⟨ ⟩, U+27E8 and U+27E9, respectively. This may
be font-related. The "special" font is used for displaying symbols, which
maps to the first available font in the following list:

- Standard Symbols PS
- Standard Symbols L
- Symbol
- serif
- oblique


The first two are included in the URW Base35 fonts, which as I explained
are sanely omitted from the web-demo, as it would add a big hit to
load-time. =) Could you try installing the StandardSymbolsPS font from
GhostScript's fonts repo?


On 23 April 2018 at 09:34, G. Branden Robinson  wrote:

> At 2018-04-23T09:04:25+1000, John Gardner wrote:
> > Well, here it is:
> >
> > https://rawgit.com/Alhadis/Roff.js/web-demo/index.html
> >
> > Some modifications were needed for web-delivery, and performance still
> > isn't optimal, but it works. You'll need a relatively recent browser to
> use
> > it (anything released within the last year should do).
> >
> > Few things to note before you try it:
>
> This looks fantastic!  Thank you for doing this work!
>
> I'd love to see what the source looks like, but when I alter the URL, I
> get a bunch of 404s.
>
> >- *Some fonts may look different.* Browsers handle font-rendering,
> which
> >means the base 35 PDF fonts won't be visible in the renderer unless
> they've
> >also been installed in your system's usual fonts directory.
>
> I found a possible Unicode handling problem.  In the attached ditroff
> output, note that the angle brackets around the email address in the
> "AUTHORS" section are rendered as different glyphs altogether.
>
> >- *There's an issue with zooming.* This is what I'm stuck on, and when
> >Branden offered help with matrix calculations, I decided the best way
> of
> >explaining was with a working demo.
> >
> >If you zoom in using the *100%* menu, you'll notice you can't scroll
> >left or upwards. That's because the page contents extend past the
> top-left
> >corner of the browser window, and we all know you can't scroll past
> the
> >window's origin corner.
>
> I see what you mean.  I don't think there's a matrix math problem here.
> If I had to guess, you are doing a coordinate transform from document
> coordinates to canvas (and/or browser window) coordinates, and clamping
> the wrong pair.
>
> For instance, if I zoom a document to 150%, there is obviously document
> content off-screen to the left.  So the x coordinate is negative in the
> browser window, but of course it is still positive in the document's
> coordinate frame.
>
> I know nothing about JavaScript frameworks (apart from the existence of
> this "canvas" thing, which is a fairly generic term for a drawing window
> anyway).
>
> Anyway, if I can get my hands on the source, maybe we can put our heads
> together on the problem.
>
> Great work!
>
> --
> Regards,
> Branden
>

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

[John Gardner]

It's taken me several hours to write this, so it damn well better be
enlightening.

> What i meant by the above sentence is that the CSS you gave,
> with the exception of the dfn{} and kbd{} selectors, selects
> nothing based on kind or class of content or semantic function.
> …
> consequently, the EXAMPLES section is indeed rendered in a
> misleading way on your example page

Actually, that stylesheet is unfinished. It's because of the browser's
default styling that most of the page's content is convincingly styled. As
for the examples section, yeah, it was jarring enough I pushed a fix just
for that. Note the selector I used in the ruleset
:
‘samp kbd’ applies its properties to any  element nested inside a
, which as the spec states

represents
the part of a user's input as echoed back by the system (for a command
prompt, that means the entire line). Contextually applying or removing
properties is common in CSS.

> So, with your stylesheet, almost all semantic information from all
> macros seems completely unhandled to me - or what am i missing?

I don't understand what you mean when you say "semantic information". The
stylesheet is building off the default browser styling, which doesn't need
to be repeated. It's senseless to write this, for example:

b { font-weight: bold; }
i { font-style: italic; }

u { text-decoration: underline; }


... because  tags are already bold by default,  tags are italic by
default, etc. The same is true for this:

kbd { font-weight: bold; }



Since a browser's default styling varies between vendors, it's common
practice to use something like Normalize.css
 to smooth out variances. I
use a modified
version of it

which the HTML page I wrote uses.

> They are not redundant. Their purpose is to display the semantic
> function of the word in a tooltip when hovering the mouse over it.

What the hell. Why? Is every reader expected to understand what Ar means if
the cursor rolls over “*options”* or what-have-you? I'm puzzled, and can't
see any *practical* reason for this. Compare that with the tooltips of the
links you mentioned, which show a short summary for *unrelated* content:

The HTMLElement interface represents any HTML element.
Some elements directly implement this interface, others
implement it via an interface that inherits it.


> The title element would be read *in addition* to the contents of
> the element, rather than instead of the contentis, right?

No. In place of. Moreover, this depends on how a screen-reader is
configured to handle title attributes.

> That is *not* at all what i want.  It is vital that any browser,
> even those i never heard of, is able to show this information to
> the user.
>
> It is neither "non-visible" nor "private" data, but an important
> part of the output, to be shown directly to the user.

Again, you'll have to explain why tag-names in a tooltip are at all
relevant to the authored material. If information is important for the
reader, it should obviously be part of the content itself. Whether
something is an argument, a flag, or a command modifier should be quite
evident to a reader by context.

> I want the output to be comprehensible even without any stylesheet.

I'd say the following is comprehensible without *anything*:

[-ac] [-I os=name] [-K encoding] [-mdoc | -man]


> I could not find any HTML element that is adequate for fixed
> syntax elements and clearly distinguishable from example code.
> Can you point me to one?

What do you mean by "fixed syntax"? Monospaced text? There are several:

   -   is
   used to represent user input verbatim. Historically, this was only used to
   represent keys on a keyboard (hence the name). Its meaning was broadened in
   HTML5 to refer to any form of user input: menus, command lines, spoken
   commands, et al.
   -  
   is used for program output, such as a command transcript
   

   .
   -   is
   used for anything else, and is typically what you'll use for inline
   monospace text. For code blocks, it should be used inside 
   :
e.g., 
   … . Note that  alone doesn't mean source code: it
   could be used for chat logs and ASCII art, for example. Furthermore, it
   doesn't imply a fixed-pitch typeface will *always* be used: simply that
   whitespace must be preserved by the user-agent verbatim.


> I dimly remember that i considered that, but decided against it
> because 

Re: [groff] Now online: gropdf / grops previewer

[G. Branden Robinson]

At 2018-04-23T09:04:25+1000, John Gardner wrote:
> Well, here it is:
> 
> https://rawgit.com/Alhadis/Roff.js/web-demo/index.html
> 
> Some modifications were needed for web-delivery, and performance still
> isn't optimal, but it works. You'll need a relatively recent browser to use
> it (anything released within the last year should do).
> 
> Few things to note before you try it:

This looks fantastic!  Thank you for doing this work!

I'd love to see what the source looks like, but when I alter the URL, I
get a bunch of 404s.

>- *Some fonts may look different.* Browsers handle font-rendering, which
>means the base 35 PDF fonts won't be visible in the renderer unless they've
>also been installed in your system's usual fonts directory.

I found a possible Unicode handling problem.  In the attached ditroff
output, note that the angle brackets around the email address in the
"AUTHORS" section are rendered as different glyphs altogether.

>- *There's an issue with zooming.* This is what I'm stuck on, and when
>Branden offered help with matrix calculations, I decided the best way of
>explaining was with a working demo.
> 
>If you zoom in using the *100%* menu, you'll notice you can't scroll
>left or upwards. That's because the page contents extend past the top-left
>corner of the browser window, and we all know you can't scroll past the
>window's origin corner.

I see what you mean.  I don't think there's a matrix math problem here.
If I had to guess, you are doing a coordinate transform from document
coordinates to canvas (and/or browser window) coordinates, and clamping
the wrong pair.

For instance, if I zoom a document to 150%, there is obviously document
content off-screen to the left.  So the x coordinate is negative in the
browser window, but of course it is still positive in the document's
coordinate frame.

I know nothing about JavaScript frameworks (apart from the existence of
this "canvas" thing, which is a fairly generic term for a drawing window
anyway).

Anyway, if I can get my hands on the source, maybe we can put our heads
together on the problem.

Great work!

-- 
Regards,
Branden
x T pdf
x res 72000 1 1
x init
p1
x font 5 TR
f5
s1
V48000
H72000
md
DFd
tPIC2GRAPH(1)
h111510
tGeneral
wh2500
tCommands
wh2500
tManual
h111510
tPIC2GRAPH(1)
n12000 0
V84000
H72000
x X devtag:.NH 1
x font 16 TB
f16
s10950
V84000
H72000
tN
H79687
tAME
wh2738
x X devtag:.eo.h
V84000
H107972
n12000 0
f5
s1
V96000
H108000
tpic2graph
wh2500
C\-
wh8140
tcon
H172670
tv
H177520
tert
wh2500
ta
wh2500
tPIC
wh2500
tdiagram
wh2500
tinto
wh2500
ta
wh2500
tcropped
wh2500
timage
n12000 0
V112800
H72000
x X devtag:.NH 1
f16
s10950
V112800
H72000
tSYNOPSIS
wh2738
x X devtag:.eo.h
V112800
H128283
n12000 0
V124800
H108000
x X devtag:.col 1
s1
V124800
H108000
tpic2graph
wh2500
x X devtag:.col 2
f5
V124800
H153840
t[
f16
C\-
h5700
tunsafe
f5
t]
wh2500
t[
f16
C\-
h5700
tf
H208590
tormat
x font 18 TI
f18
h2500
toutput-format
f5
h680
t]
wh2500
t[
f16
C\-
h5700
teqn
f18
h2500
tdelimeter
f5
h730
t]
wh2500
t[
f18
h200
tcon
H388250
tvert-options
f5
h270
t]
n12000 0
V141600
H72000
x X devtag:.NH 1
f16
s10950
V141600
H72000
tDESCRIPTION
wh2738
x X devtag:.eo.h
V141600
H150787
n12000 0
f5
s1
V153600
H108000
tReads
wh2500
ta
wh2500
tPIC
wh2500
tprogram
wh2500
tas
wh2500
tinput;
wh2500
tproduces
wh2500
tan
wh2500
timage
wh2500
Cfi
h5560
tle
wh2500
t(by
wh2500
tdef
H354250
tault
wh2500
tin
wh2500
tPortable
wh2500
tNetw
H439420
tork
wh2500
tGraphics
wh2500
tformat)
n12000 0
V165600
H108000
tsuitable
wh2500
tfor
wh2500
tthe
wh2500
tW
H179130
teb
wh2500
tas
wh2500
toutput.
wh5000
tAlso
wh2500
ttranslates
wf16
h2500
teqn
f5
t(1)
wh2500
tconstructs,
wh2500
tso
wh2500
tit
wh2500
tcan
wh2500
tbe
wh2500
tused
wh2500
tfor
wh2500
tgenerating
wh2500
timages
wh2500
tof
n12000 0
V177600
H108000
tmathematical
wh2500
tformulae.
n12000 0
V194400
H108000
tPIC
wh2500
tis
wh2500
ta
wh2500
trather
wh2500
te
H172280
txpressi
H200360
tv
H205210
te
wh2500
tgraphics
wh2500
tminilanguage
wh2500
tsuitable
wh2500
tfor
wh2500
tproducing
wh2500
tbox-and-arro
H448240
tw
wh2500
tdiagrams
wh2500
tof
wh2500
tthe
n12000 0
V206400
H108000
tkind
wh2500
tfrequently
wh2500
tused
wh2500
tin
wh2500
ttechnical
wh2500
tpapers
wh2500
tand
wh2500
tte
H294200
txtbooks.
wh5000
tThe
wh2500
tlanguage
wh2500
tis
wh2500
tsuf
H411160
Cfi
h5560
tciently
wh2500
Cfl
h5560
te
H456290
txible
wh2500
tto
wh2500
tbe
wh2500
tquite
n12000 0
V218400
H108000
tuseful
wh2500
tfor
wh2500
tstate
wh2500
tcharts,
wh2500
tPetri-net
wh2500
tdiagrams,
wh2500
Cfl
h5560
to
H287720
tw
wh2500
tcharts,
wh2500
tsimple
wh2500
tcircuit
wh2500
tschematics,
wh2500
tjumper
wh2500
tlayouts,
wh2500
tand
wh2500
tother
n12000 0
V230400
H108000
tkinds
wh2500
tof
wh2500
tillustration
wh2500
tin
H196220
tv
H201020
tolving
wh2500
trepetiti
H257160
tv
H262010
te
wh2500
tuses
wh2500
tof
wh2500
tsimple
wh2500
tgeometric
wh2500
tforms
wh2500
tand
wh2500
tsplines.
wh5000
tBecause
wh2500

[groff] Now online: gropdf / grops previewer

[John Gardner]

Well, here it is:

https://rawgit.com/Alhadis/Roff.js/web-demo/index.html

Some modifications were needed for web-delivery, and performance still
isn't optimal, but it works. You'll need a relatively recent browser to use
it (anything released within the last year should do).

Few things to note before you try it:

   - *This is a post-processor.* Make sure you use groff's -Z switch (or
   troff directly) if you're testing it with your own documents. You'll
   need to pipe it to your system's clipboard and paste it into the *Edit
   Source* dialogue.

   Normally, Atom handles this procedure transparently by piping the
   editor's contents through Groff in a separate process. Webpages don't have
   access to system binaries (thankfully), so this is the best I can do.

   - *Heirloom Troff output isn't perfect.* This is a known issue I intend
   to fix in a future release. At the moment, the renderer is heavily reliant
   on the ‘w’ and ‘n’ output commands to identify where a word ends. Groff
   uses these sequences consistently, but Heirloom doesn't. They're also
   omitted from certain eqn(1) constructs which also need fixing.

   - *Some fonts may look different.* Browsers handle font-rendering, which
   means the base 35 PDF fonts won't be visible in the renderer unless they've
   also been installed in your system's usual fonts directory.

   I have this taken care of by bundling
    with the editor-package
   all 35 URW's core fonts. For the sake of your bandwidth, I've opted *not* to
   embed ~3 MBs of fonts into the page: if basic fonts seem to be missing, you
   can probably fix it by installing the fonts from upstream
   

   .

   - *There's an issue with zooming.* This is what I'm stuck on, and when
   Branden offered help with matrix calculations, I decided the best way of
   explaining was with a working demo.

   If you zoom in using the *100%* menu, you'll notice you can't scroll
   left or upwards. That's because the page contents extend past the top-left
   corner of the browser window, and we all know you can't scroll past the
   window's origin corner.

Other than that, enjoy!

- John

Re: [groff] Savannah bug field usage protocol

[G. Branden Robinson]

At 2018-04-22T11:29:39+0100, Colin Watson wrote:
> On Sat, Apr 21, 2018 at 05:43:12PM -0400, G. Branden Robinson wrote:
> > 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?
> 
> I agree with the sentiment, but do the ~40 lines of NEWS entries since
> 1.22.3 really reflect the ~1900 lines of ChangeLog for the same period?
> I'm not really qualified to prepare updates there, but the ratio seems
> unusually low to me.

I'm sure those 40 lines don't cover all the work.

We have a release manager now; I'd say it's up to Bertrand to delegate
that task to some unfortunate victim, er, volunteer.  ;-)

-- 
Regards,
Branden


signature.asc
Description: PGP signature

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

[Ingo Schwarze]

Hi John,

John Gardner wrote on Sat, Apr 21, 2018 at 04:48:33PM +1000:

> 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.

Sounds like you might have valueable input that could end up
improving the mandoc -Thtml output.  Note that i did *not*
claim that i specialize in anything related to HTML/CSS, which
i actually do not.  Quite to the contrary, whenever i had
questions related to HTML/CSS, i had a hard time finding any
developer who knew much about it.  So i might finally get some
real help, looking forward to that...

>> 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).

Wait - the point of CSS is to select adequate presentation
for content of a given kind or class, right?  So the CSS, on its
input side, first needs to be told, by HTML elements and attributes,
what kind or class of content some text belongs to, and then has
to select the presentational attributes using selectors addressing
these kinds and classes of HTML elements, right?

What i meant by the above sentence is that the CSS you gave,

https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/manpage.css

with the exception of the dfn{} and kbd{} selectors, selects nothing
based on kind or class of content or semantic function.  What you
do with def{} handles one single macro, and kbd{} is used for very
different kinds of content that need completely different formatting,
namely fixed syntax elements like command line options (.Fl) and
fixed option arguments (.Cm) on the one hand but also code examples
(.Dl) on the other hand - consequently, the EXAMPLES section is
indeed rendered in a misleading way on your example page, compare to

  https://man.openbsd.org/mandoc.1#EXAMPLES

So, with your stylesheet, almost all semantic information from all
macros seems completely unhandled to me - or what am i missing?

> Redundant title attributes on everything.

They are not redundant.  Their purpose is to display the semantic
function of the word in a tooltip when hovering the mouse over it.
I'll gladly do that in a better way if i find one or someone directs
me into the right direction, but when i read the CSS standard, i
failed to find any other way.

As a matter of fact, the very document you quote uses title
attributes for exactly the same purpose:

https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*

Look at the source code for the elements that show tool tips,
like "HTMLElement" or "DOMStringMap".

> 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.

The title element would be read *in addition* to the contents of
the element, rather than instead of the contentis, right?  That
would actually be useful, because not being able get a visual
impression of the page as a whole, hearing the page word by word,
it is even harder to correctly guess the semantic function of key
words because you at first lack the necessary context of these
words, which a visual impression of the page can provide without
reading anything.  Besides, listening to a screen reader, you
wouldn't hear what is bold or italic, so getting the meta-information
across in some different, verbal way seems useful to me.

I admit, though, that i relatively rarely work with people who use
screen readers, only every few months maybe, and never asked them
to test the mandoc output.

>If you want to attach page or application-specific metadata to
>elements, use data-*
>
> 
>instead.

Looking at the link given there,

https://html.spec.whatwg.org/multipage/dom.html#embedding-custom-non-visible-data-with-the-data-*-attributes

i read:

  3.2.6.6 Embedding custom non-visible data with the data-* attributes
  [...]
  These attributes are not intended for use by software that is not
  known to the administrators of the site that uses the attributes.

That is *not* at all what i want.  It is vital that any browser,
even those i never heard of, is able to show this information to
the user.

It is neither "non-visible" nor "private" data, but an important
part of the output, to be shown directly to the user.

So i don't quite understand why you suggest data-*.
No user would never see those attributes, right?

> *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 

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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sat, Apr 21, 2018 at 03:06:14AM -0400:
> At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote:
>> John Gardner wrote:
>>> 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,

True.  The convention "write the first argument of .TH, .Dt,
and all arguments of .Sh in ALL CAPS" is a premature presentational
decision.

> 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

I strongly agree with that: once done, it cannot be undone.

> 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.

I mildly agree with that sentiment, as explained in my other
posting - except for the large amount of work it would cause me.

> 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.

So what?  With two explicit OKs - namely, from Michael Kerrisk and
Jason McIntyre - i would switch that right away and not even provide
a knob for people to turn.  Let them be shocked.  Things change.

The problem is, i have to change several thousand manual pages first
even if we all agree it would be nice to have - is that amount of
work well invested, or are there more important things to do?


The point at *this* point of the thread is a *completely*
different one:  HTML anchors are not only used for section
headers, but also for command names, function names, variable
names, and many other syntax elements where case is no doubt
syntactically important.  So as long as the section name
appearing in a specific manual page is "EXIT STATUS", the
anchor has to be exactly that, and no case variation.

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

Yours,
  Ingo

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

[Ingo Schwarze]

Hi Larry,

Larry Kollar wrote on Sat, Apr 21, 2018 at 10:44:43AM -0400:

> 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.

Not a real problem, your pages are still readable and correct -
and you argue they are even more readable and nicer.  Fair enough.

Some parsers may warn, including mandoc:

mandoc: :1:5: STYLE: lower case character in document title: Dt foo
mandoc: :1:5: STYLE: lower case character in document title: TH foo

But it's only flagged as a STYLE level issue, meaning that there
is no ambiguity, portability, or formatting problem.

> 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.

Err, no, serious layering violation alert.  In implementations
were the formatter and man(1) are separate programs, the man(1)
utility should please *not* try to change the formatting, not
even in a well-intentioned way.  It should only display the
rendered version it got, unchanged.

The formatter can't do the tranformation either: once the case of
some string was clobbered into ALL CAPS, going back programmatically
is impossible, information was lost.  For example, the OpenBSD
ipsec.conf(5) manual contains

  .Sh IPSEC.CONF FILE FORMAT

and it might contain

  .Sh IPSEC AUTOMATIC KEYING

No formatter can figure out that the correct capitalization is

  .Sh ipsec.conf file format
  .Sh IPsec automatic keying

I'm not necessarily opposed to getting rid of this antiquated
convention (though i would have to check with Jason, who sometimes
is aware of arguments that i miss), except that i would probably
be the poor guy who would have to edit thousands of manual pages,
a process that can only partly be automated and certainly requires
checking all of them by hand.

You will understand that while i see the point why the convention
is not good - and even worse for .TH and .Dt than for .Sh - i'm not
thrilled by the idea of getting rid of it so late in the game, for
the sheer volume of churn it would cause.

Yours,
  Ingo

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

[Ingo Schwarze]

Hi Nate,

Nate Bargmann wrote on Sat, Apr 21, 2018 at 12:59:16PM -0500:

> 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.

I think it depends on where you come from.  Not counting pure-ASCII
text editing for fixed-width line printers that couldn't do *any*
kind of formatting at all in the early 80ies, i grew up with LaTeX
as *the* one and only text processor for serious work (not counting
the occasional Word document for quickly preparing a leaflet to
distribute on Campus, which we didn't really take seriously in the
sense of "text processing").  And when i typeset formulae for
theoretical high enery phsics, i used to not only make sure that
the content of the formulae was correct and that the printed output
was easy to read and pretty, but also that the source code was
easily human-readable and conveyed the structure of the formulae
that were often several lines long.  That applied even when i had
to design new glyphs for specialized symbols, typically by grouping
existing component glyphs, or to code new environments for specialized
function-like notations.

> 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.

I work on mdoc(7) manual pages a lot, and i almost never look at
any kind of output to see whether the final formatting comes out
in the desired visual form.  While writing, i exclusively think
about the logical structure of the text and the semantic function
of each word and symbol.  (I do periodically check the rendered
console output, though - but only because finding typos is easier
in the rendered form than in the source code.)  I certainly
never look at HTML or PDF/PostScript output to see whether it
comes out right.  I just *know* it will - or if it won't then
that's a bug in the formatter which i have to fix.

This anecdotal evidence still confirms your observation, though.
The chief maintainer of the OpenBSD manuals, Jason McIntyre, trained
himself for many years by editing mdoc(7) manual pages with an
ancient, now long obsolete version of groff, groff-1.15, which was
much more quirky than the current, much cleaner groff after Werner's
major work that led up to groff-1.17.  I know definitely that Jason
is still in the habit of checking that every change renders in the
way he desires.  During those years, he got so used to work around
quirks in the parsers and formatters by tweaking the source that
for some years, i found more bugs in mandoc by inspecting his
workaround commits than by explicit bug reports - even though he
did report many bugs.  He *expected* the formatter to be quirky and
thoroughly trained himself to "tweak for effect" by using quirky
software for a long time.

That effect does exist, but is is not unavoidable, and i think
it is even reversible, though of course unlearning is always
harder than learning.

Yours,
  Ingo

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

[Ingo Schwarze]

Hi James and Nate,

James K. Lowden wrote on Sat, Apr 21, 2018 at 06:58:59PM -0400:
> On Sat, 21 Apr 2018 08:16:36 -0500 Nate Bargmann wrote:

>> 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.  

Yes, confirmed, that is entirely accurate.  So the program
doing exactly that will be ten years old the coming winter.

It is also the reason why the former, original name of the mandoc
project, before it grew support for the man(7) input language
and the -Tascii, -Tutf8, -Tps, and -Tpdf output modes was
chosen as "mdocml" by the original author, Kristaps Dzonsons:
It meant "mdoc->html", i.e. "go directly from mdoc(7) to HTML,
without the devastating detour via the troff intermediate format".

Yours,
  Ingo

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

[Deri James]

On Sat 21 Apr 2018 08:16:36 Nate Bargmann wrote:
> 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.

You might consider supporting mdoc macros. You may have seen:-

http://chuzzlewit.co.uk/WebManPDF.pl/man:/7/groff_mdoc

Which shows what a preprocessor inserting Keith's pdfmark extensions can do. 
Compare with:-

http://chuzzlewit.co.uk/WebManPDF.pl/man:/7/groff_man

Which has less semantic markup to use.

Note this runs on a very small arm powered computer, so there is a noticeable 
delay in serving the pages, it is much faster on my desktop. 

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

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Sun, Apr 22, 2018 at 02:42:27AM -0400:

> Follow-up Comment #6, bug #53547 (project groff):
> 
> I did not find any need for this:
> 
> \# The next argument must be longer than the indent from .TP (8n)
> 
> or the spaces they refer to, nor for the transparent line indicators.

I don't have the slightest idea what Bjarni thought when
proposing this change:

@@ -276,7 +276,10 @@
 in the order shown.
 .
 .TP
-.B .RP [no]
+\#.B .RP [no]
+\!.B .RP \c
+\# The next argument must be longer than the indent from .TP (8n)
+.RB [ no ]\ \ \ \ \ \"
 Specifies the report format for your document.
 .
 The report format creates a separate cover page.

It looks totally bogus to me on more than one level.  You most
certainly do not want any of "\#", "\!", "\ \ \ " in a manual
page and you also most certainly do not want

  .B anything \c
  .RB anything

> Things seem to be rendering fine both to the utf8 and PDF output
> devices.  (The underlying changes involving the font style used
> for option brackets and similar, are legitimate.)
> 
> Is mandoc doing something differently?

The rendering of

  .TP
  .BR ".RP " [ no ]
  Specifies the report format for your document.

in the context of groff_ms(7) is identical in groff and mandoc.
(Otherwise, it would be a bug in mandoc.  :)


Only the SYNOPSIS differs; groff renders:

   groff -ms [option ...] [input-file ...]

   groff -m ms [option ...] [input-file ...]

Mandoc renders:

   [option ...] [input-file ...] [option ...] [input-file ...]

because it does not implement the .SY macro.  That macro is exceedingly
rare in practice.  I scanned all ten thousand third-party software
packages in the OpenBSD ports tree and could not find a single use
outside groff itself.

I think the macro should be deleted, first from the few groff manual
pages using it, then from man-ext.tmac.  It is a half-hearted attempt
at sneaking semantic markup into a purely presentational language
that (forunately) never got traction anywhere.

Yours,
  Ingo

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

Re: [groff] Savannah bug field usage protocol

[Colin Watson]

On Sat, Apr 21, 2018 at 05:43:12PM -0400, G. Branden Robinson wrote:
> At 2018-04-21T14:21:03+0100, Ralph Corderoy wrote:
> > 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?

I agree with the sentiment, but do the ~40 lines of NEWS entries since
1.22.3 really reflect the ~1900 lines of ChangeLog for the same period?
I'm not really qualified to prepare updates there, but the ratio seems
unusually low to me.

-- 
Colin Watson   [cjwat...@debian.org]

[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):

 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

[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: 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] 04/04: groff_ms(7): Make style fixes.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit dbfa0b757b920eb6c44a2fd319180f525b138a28
Author: G. Branden Robinson 
Date:   Sun Apr 22 02:38:52 2018 -0400

groff_ms(7): Make style fixes.

* Escape hyphens used as minus signs or embedded in macro parameters
  (see SN-STYLE, SN-DOT, and SN-NO-DOT).
* Render option brackets in roman, not bold, in macro descriptions.
* Use paired directional double quotes to clarify use-versus-mention
  scenarios.
* Remove spurious \- from the name of the ms macros (they're not the
  "-ms" macros).
* Fix subject/verb agreement.  Two things do not "denotes" something.
* Stop captializing a sentence following a colon.
* Use the Oxford comma.
* Remove unnecessary commas from dependent clauses.
* Make minor tweaks to phrasing.
* Wrap one long line.

Based on changes suggested by Bjarni Ingli Gislason.

Fixes bug https://savannah.gnu.org/bugs/index.php?53547.

Signed-off-by: G. Branden Robinson 
---
 tmac/groff_ms.7.man | 162 ++--
 1 file changed, 95 insertions(+), 67 deletions(-)

diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 5f54924..b6dc65d 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -240,7 +240,7 @@ _
 FL Footnote length next footnote   \[rs]n[LL]*5/6
 FI Footnote indent next footnote   2n
 FF Footnote format next footnote   0
-FPSPoint size  next footnote   \[rs]n[PS]-2
+FPSPoint size  next footnote   \[rs]n[PS]\-2
 FVSVert.\& spacing next footnote   \[rs]n[FPS]+2
 FPDPara.\& spacing next footnote   \[rs]n[PD]/2
 _
@@ -272,7 +272,7 @@ Use the following macros to create a cover page for your 
document
 in the order shown.
 .
 .TP
-.B .RP [no]
+.BR ".RP " [ no ]
 Specifies the report format for your document.
 .
 The report format creates a separate cover page.
@@ -301,7 +301,8 @@ on page\~1 of the document.
 The default is to suppress the header.
 .
 .TP
-.BI ".DA [" xxx ]
+.B .DA\c
+.RI " [" xxx ]
 (optional) Print the current date,
 or the arguments to the macro if any,
 on the title page (if specified)
@@ -311,7 +312,8 @@ This is the default for
 .IR nroff .
 .
 .TP
-.BI ".ND [" xxx ]
+.B .ND\c
+.RI " [" xxx ]
 (optional) Print the current date,
 or the arguments to the macro if any,
 on the title page (if specified)
@@ -344,7 +346,7 @@ Specifies the author's institution.
 You can specify multiple institutions.
 .
 .TP
-.B .AB [no]
+.BR ".AB " [ no ]
 Begins the abstract.
 .
 The default is to print the word
@@ -379,10 +381,11 @@ macro indents all text at both left and right margins
 by the amount of the register
 .BR QI .
 .
-The effect is identical to the HTML
+The effect is reminiscent of the HTML
 .B 
+tag.
 .
-The next paragraph or heading returns margins to normal.
+The next paragraph or heading returns the margins to normal.
 .
 .B QP
 inserts the vertical space specified in register
@@ -406,7 +409,7 @@ and
 .B QE
 insert the inter-paragraph spacing specified in
 .B PD
-and the text is indented on both sides by the amount of
+and the text is indented on both sides by the amount of register
 .BR QI .
 .
 The text between
@@ -422,7 +425,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,
@@ -488,8 +492,8 @@ macros print headings in
 using the same font family and point size as the body text.
 .
 For output devices which support scalable fonts,
-this behaviour may be modified,
-by defining the document control registers,
+this behaviour may be modified by defining the document control
+registers
 .B GROWPS
 and
 .BR PSINCR .
@@ -580,44 +584,44 @@ is interpreted in
 basic units;
 the
 .I p
-scaling factor should be employed,
-when assigning a value specified in points.
+scaling factor should be employed when assigning a value specified in
+points.
 .
 .IP
 The style used to represent the section number,
 within a numbered heading,
 is controlled by the
-.B SN-STYLE
+.B SN\-STYLE
 string;
 this may be set to either the
-.B SN-DOT
+.B SN\-DOT
 or the
-.B SN-NO-DOT
+.B SN\-NO\-DOT
 style,
 (described below),
 by aliasing
-.B SN-STYLE
+.B SN\-STYLE
 accordingly.
 .
 By default,
-.B SN-STYLE
+.B SN\-STYLE
 is initialised by defining the alias
 .RS
 .nf
 .IP
-\&.als SN-STYLE SN-DOT
+\&.als SN\-STYLE SN\-DOT
 .fi
 .RE
 .IP
 it may be changed to the
-.B SN-NO-DOT
+.B SN\-NO\-DOT
 style,
 if preferred,
 by defining the alternative alias
 .RS
 .nf
 .IP
-\&.als SN-STYLE SN-NO-DOT
+\&.als SN\-STYLE SN\-NO\-DOT
 .fi
 .RE
 .IP
@@ -630,28 +634,28 @@ the new alias is defined.
 After invoking
 .BR .NH ,
 the assigned heading number is available in the strings
-.B SN-DOT
+.B SN\-DOT
 (as it appears in the default formatting style for numbered 

[groff] 02/04: groff_man(7): Expand command synopsis section.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 5599c6decdc82d146b216b7111adfd55fa958294
Author: G. Branden Robinson 
Date:   Sun Apr 22 01:51:43 2018 -0400

groff_man(7): Expand command synopsis section.

This section now explains in detail how to write (and read) a
command synopsis.

Also fix some style/markup issues:
* Mark the second argument to the .OP macro as optional.
* Escape the hyphens in the command synopsis input example.
* Guard ellipsis boundaries with zero-width spaces.

Signed-off-by: G. Branden Robinson 
---
 ChangeLog|   7 +++
 tmac/groff_man.7.man | 131 ++-
 2 files changed, 104 insertions(+), 34 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5ea92e1..3b7cbed 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2018-04-22  G. Branden Robinson 
+
+   groff_man(7): Expand command synopsis section.
+
+   This section now explains in detail how to write (and read) a
+   command synopsis.
+
 2018-04-12  Deri James  
 
Make PDFPIC behave the same whether -Tps or -Tpdf used.
diff --git a/tmac/groff_man.7.man b/tmac/groff_man.7.man
index f786898..e9e64a9 100644
--- a/tmac/groff_man.7.man
+++ b/tmac/groff_man.7.man
@@ -843,18 +843,22 @@ installation.
 .PP
 These macros are a convenience for authors.
 .
+Together, they produce the traditional look of a Unix command synopsis.
+.
 They also assist automated translation tools and help browsers in
 recognizing command synopses and treating them differently from
 running text.
 .
 .
 .TP
-.BI .OP " key value"
-Describe an optional command argument.
+.BI .OP " option-name"\c
+.RI " [" option-argument ]
+Indicate an optional command parameter called
+.IR option-name .
 .
-The arguments of this macro are set surrounded by option braces
-in the default Roman font; the first argument is printed with
-a bold face, while the second argument is typeset as italic.
+If the option takes an argument, specify
+.I option-argument
+using a noun, abbreviation, or hyphenated noun phrase.
 .
 .
 .TP
@@ -865,50 +869,49 @@ Takes a single argument, the name of a command.
 .
 Text following, until closed by
 .BR .YS ,
-is set with a hanging indentation with the width of
+is set with a hanging indentation of the width of
 .I command
 plus a space.
 .
-This produces the traditional look of a Unix command synopsis.
-.
 .
 .TP
 .B .YS
-This macro restores normal indentation at the end of a command
-synopsis.
+End synopsis.
+.
+Restore normal indentation.
 .
 .
 .PP
-Here is a real example:
+For example,
 .
 .
 .IP
 .EX
 \&.SY groff
-\&.OP \e-abcegiklpstzCEGNRSUVXZ
-\&.OP \e-d cs
-\&.OP \e-f fam
-\&.OP \e-F dir
-\&.OP \e-I dir
-\&.OP \e-K arg
-\&.OP \e-L arg
-\&.OP \e-m name
-\&.OP \e-M dir
-\&.OP \e-n num
-\&.OP \e-o list
-\&.OP \e-P arg
-\&.OP \e-r cn
-\&.OP \e-T dev
-\&.OP \e-w name
-\&.OP \e-W name
+\&.OP \e\-abcegiklpstzCEGNRSUVXZ
+\&.OP \e\-d cs
+\&.OP \e\-f fam
+\&.OP \e\-F dir
+\&.OP \e\-I dir
+\&.OP \e\-K arg
+\&.OP \e\-L arg
+\&.OP \e\-m name
+\&.OP \e\-M dir
+\&.OP \e\-n num
+\&.OP \e\-o list
+\&.OP \e\-P arg
+\&.OP \e\-r cn
+\&.OP \e\-T dev
+\&.OP \e\-w name
+\&.OP \e\-W name
 \&.RI [ file
-\&.IR .\e|.\e|. ]
+\e&.\e|.\e|.\e&]
 \&.YS
 .EE
 .
 .
 .PP
-produces the following output:
+produces the following output.
 .
 .
 .RS
@@ -931,18 +934,78 @@ produces the following output:
 .OP \-w name
 .OP \-W name
 .RI [ file
-.IR .\|.\|. ]
+\&.\|.\|.\&]
 .YS
 .RE
 .
 .
 .PP
-If necessary, you might use
+Multiple
+.B .SY/.YS
+blocks can be specified,
+for instance to distinguish differing modes of operation of a complex
+command like
+.BR tar (1);
+each will be separated by a paragraph space.
+.
+If necessary, you can use a
 .B br
-requests to control line breaking.
+request to insert a mandatory line break.
+.
+.
+.PP
+Several features of the above example are of note.
+.
+.
+.IP \(bu
+The command and option names are presented in
+.B boldface
+to cue the user that they should be input literally.
+.
+.
+.IP \(bu
+Option dashes are specified with the \(lq\e\-\(rq escape sequence;
+this is an important practice to make them clearly visible and to
+facilitate cut-and-paste from the rendered man page to a shell prompt or
+text file.
+.
 .
-You can insert plain text as well; this looks like the traditional
-(unornamented) syntax for a required command argument or filename.
+.IP \(bu
+Option arguments and command operands are presented in
+.I italics
+(underlined on some output devices, such as terminals and emulators),
+to cue the user that they must be replaced with appropriate text.
+.
+.
+.IP \(bu
+Symbols that are neither to be typed literally nor simply replaced
+appear in plain (roman) style;
+brackets surround optional arguments,
+and an ellipsis indicates that the previous syntactical element may be

[groff] 03/04: groff_ms(7): Correct apparent factual error.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit ce142838ee78eb2b247e841ed73fac0e59c55584
Author: G. Branden Robinson 
Date:   Sun Apr 22 02:16:23 2018 -0400

groff_ms(7): Correct apparent factual error.

It doesn't seem to actually be possible to manipulate the document's
base font face or style via number registers.

Also, "document's type" was used pretty confusing given that the term
"document type" was used to mean something completely different in the
immediately preceding paragraph.

Signed-off-by: G. Branden Robinson 
---
 tmac/groff_ms.7.man | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 0b0b58a..5f54924 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -105,8 +105,9 @@ are specific to AT or Berkeley, and are not supported in
 .TP
 .B "Format and layout"
 By setting number registers,
-you can change your document's type (font and size),
-margins, spacing, headers and footers, and footnotes.
+you can change your document's
+margins, spacing, headers and footers, footnotes,
+and the base point size for the text.
 .
 See
 .I "Document control registers"

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

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

[G. Branden Robinson]

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

I did not find any need for this:


\# The next argument must be longer than the indent from .TP (8n)


or the spaces they refer to, nor for the transparent line indicators.  Things
seem to be rendering fine both to the utf8 and PDF output devices.  (The
underlying changes involving the font style used for option brackets and
similar, are legitimate.)

Is mandoc doing something differently?


___

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):

Severity:1 - Wish => 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