groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Groff] More referenceability for -mdoc would be an improvement!?


From: Steffen Nurpmeso
Subject: Re: [Groff] More referenceability for -mdoc would be an improvement!?
Date: Mon, 15 Sep 2014 17:50:19 +0200
User-agent: s-nail v14.7.6-15-gc1887ab

Hallo Ingo,

Ingo Schwarze <address@hidden> wrote:
 |Hi Steffen,
 |
 |Steffen Nurpmeso wrote on Mon, Sep 15, 2014 at 01:53:29PM +0200:
 |
 |> So next week (hopefully) i will sit down and write a patch against
 |> current -mdoc that implements an .Ix stub and documents it, adding
 |> an entry to the bug tracker.
 |
 |Take all i'm saying below with a grain of salt; i didn't spend the
 |time to really think it through yet, so i may be overlooking important
 |constraints or requirements.  I'm not even sure .Ix is the right
 |approach, it's just a candidate.  Having a prototype may be useful,
 |though, to play with it and help completing the design.
 |
 |I have a hunch jmc@ won't like .Ix and might call it too complicated,
 |too much work to maintain, and not providing enough value.  Quite
 |likely, we will have to both simplify the concept further and make
 |it more powerful before it stands a real-world chance.

Now let me say "wow" -- i have rarely seen the addition of
a single macro adding so many possibilities on the backend side,
and even beyond that!  Talking to your .Ix multiplexer :), that
is.

But nothing would prevent a far future manual indexer to work this
out:

  address@hidden roff.git]$ apropos el_getc
  editline(3), el_init(3), el_end(3), el_reset(3), el_gets(3)[.]
  address@hidden ]$ apropos EL_SETTC
  EL_SETTC: nothing appropriate

Only .Nm entries are found, nothing else!
If this variable had instead been declared via .Ix too then not
only would there be an interactivity improvement (possible), but
an indexer could also generate a better index (beyond full-text
search).

 |For a real-world chance, we might have to start without *any* new
 |macro or syntax and without any need to change anything in
 |existing manuals, demonstrate that the concept can provide considerable
 |real-world value, develop it as far as possible without causing any
 |new maintenance effort, and only then introduce new syntax to
 |handle those (hopefully few) cases that can't be autodetected.
 |
 |> I think .Ix should at least support referencing of Dv, Ev, Fn, Ic,
 |> Va, printing an error message for other uses.  Does this sound
 |> right / sufficient / acceptable to mandoc(1)?
 |
 |Looking at "Macro Keys" in apropos(1), i see some more:
 |
 |Important: Fl Cm Ar Fa

I considered them not so important, but of course, referencing to
behaviours of command line options i use very often myself, so
i think this was a wrong consideration.

But -- why .Fa?  I cannot imagine why someone would like to index
names of function arguments, or be able to hyper-ref them.  Isn't
that just markup to be able to let some _name_ standout in a block
of text?

 |Maybe:        Pa (would usually point to a FILES entry)
 | Er (would usually point to an ERRORS entry)
 |
 |Fo must act like Fn in this respect.

Ok.

 |If any of these cause trouble, they can of course be left out
 |at first.  The implementation ought to be mostly macro-agnostic,
 |though.  So if adding another macro to the list causes any
 |significant work, it's probably badly implemented.

Ok.  I think too adding a macro to the set of .Idx'able macros
should not require more than adding ". doc-idx-add Myname
Thisanchor" to the macro body (or that of the shared
implementation macro).  And that in turn has to look at the .Ix
stack and eventually pop it, writing through index information to
the backend, if that is supported; i think via some additional
doc-idx-write macro that eventually gets defined to a non-noop.
I think i'll try to go that route.

 |> Since the improved referencing / indexing capabilities will refer
 |> to new or actively updated manuals only i think it is acceptable
 |> to require that one of the first commands be an ".Ix 1" to
 |> indicate that the document makes use of the extensions --
 |
 |I still don't see the point at all.  It's just a useless knob.
 |Either it works and can be enabled by default, or it doesn't
 |work, then it should be deleted.  I don't want options.
 |
 |Besides, .Ix 1 is terrible syntax.  To follow mdoc(7) standards,
 |it would have to be something like .Ix -enable (compare to
 |.An -nosplit).  But such feature switches creating state are not
 |the best part of the mdoc(7) language and i don't want more of
 |them.  The language should have as little global state as possible.
 |
 |> this
 |> would affect the -mandoc mode of mandoc(1) as that currently
 |> doesn't detect the right macro set when .Ix comes first (instead
 |> of .Dd, .Dt and ...), yet i think placing it first would be a
 |> logical decision from a manual writers point of view.
 |
 |If at all, it definitely has to be after the preample (i.e. after
 |.Os), maybe even after .Nd.  Even if you need it at all, you
 |certainly don't need it before the start fo the content of the
 |first non-NAME section.

Well, presumably it could be placed wherever as long as the I/O
stream can be forked and then rewound, only enabling anchors and
references to them for the remaining document.  This is pretty
sure for the TTY output device; i have *absolutely* no idea about
the HTML one except that it is very slow and requires a 110+
column terminal :(.

But even if it is possible, i'm all for _requiring_ it in the
preamble for those document formats that generate, well,
a preamble.
"-enable", ok.  Better!

 |> (Unfortunately mdoc doesn't define a request that indicates a
 |> documents' version or required feature set (like e.g. perl(1)s
 |> $^UNICODE) which could be used / added to for that.  And from my
 |> point of view adding one now is complete overkill.)
 |
 |I consider specifying the language version in documents VERY harmful.
 |It just encourages the parsers to develop bloat in the form of
 |excessive backward compatibility, and it unduly encourages incompatible
 |language extensions.  I'm thankful we don't have it, and if we had,
 |it would be one of the first things i would call out for deletion.
 |
 |Not having that kind of bloat-provoking crutch is the right way to
 |make sure the language is developed responsibly.

This really gets too far, but i disagree with you in this case.

 |> I think any non-".Ix 1" that occurs without having seen the
 |> unlocking ".Ix 1" first should print an error message, too.
 |> 
 |> So consensus on the above is of course a prerequisite.
 |> 
 |> I'd also look into less(1) and write a proof-of-concept patch.
 |> (Again, the idea is to have a simple command shortcut, say, ^X,
 |> read in a decimal number, expand that to a backspace sequence and
 |> start a simple search.)
 |
 |Where is the user supposed to get that decimal number from?

Like i said, i thought of something like the lynx(1)
"keypad_mode=LINKS_ARE_NUMBERED" mode.  It places a "[NO]"

  [2]Imprint/Disclaimer

construct right before each link, the user then simply enters the
plain decimal "NO", lynx(1) says

  Follow link (or goto link or page) number: 2

and hitting return will load the page.  Very comfortable!
So this won't be possible with less(1) since entering a plain
number will move forward this number of lines (iirc), so we need
a trigger character; on the other hand no need for the followup
question, then.
Of course this modifies the output and must be taken into account
for line length and hyphenation purposes etc., which will be
a real problem for any pipeline-based implementation.

 |Integration with less(1) is very tricky because it doesn't have
 |any notion of a "current cursor position".  Integration with
 |view(1) would be much easier, but that doesn't handle input
 |piped into it.  I have no idea yet how to handle this pager
 |business.

What is so wrong with the backspace sequence?

     •^H•{^H{^H1^H}^H}^H   Item 1

     •^H•   Item [^H[1^H1]^H]2

Works for me in less(1).
As far as i understand the ISO 6429 colour and font attributes are
not ment to completely replace the backspace sequences, they only
provide for the better.  ?  _I_don't_know_.

 |> Later on, hopefully this year, i'll adjust the -- then usable --
 |> S-roff TTY mode
 |
 |What do you mean by TTY mode?

Output device (grotty).

 |> to support the two pass model that is necessary to
 |> be able to track all references -- one cannot assume that all .Dv,
 |
 |Actually, .Dv is one of the macros cooperating less willingly with .Ix.
 |For example, .Dv NULL cannot reasonably link anywhere.  Other uses,
 |like .Dv O_CREAT, will point to a place in the same page, though.
 |
 |In general, i consider .Ix a tool purely for navigating *inside*
 |one manual page.  When it comes to *external* references, .Xr
 |must be used, anyway.

Yep.  External linkage is beyond the scope of what i have in mind,
but for an integrated mandoc(1) / xyDB environment trying to
actually resolve just any entitity may be an option of yours, for
some output modes.  It would be tremendous to see a ".Xr sendmail
1" and be able to automatic see the manual in $PAGER, of course.

Well, less(1) *can* load new files...
So you propose [NR] for document internal links and [^H:^HNR] for
external ones, and [^H!^HNR] for booting a Windows VM?  :)
I think the concept is extensible, but i'd be already happy to
have document internal links...

 |> .Ev
 |
 |In a properly written manual, every variable appearing in .Ev
 |will have an entry below ENVIRONMENT, as a rule.
 |
 |> etc. that are used throughout a manual are actually defined in
 |> the same manual, right?  I assume mandoc(1) can simply traverse
 |> it's tree...
 |
 |Not sure what you are trying to say here.  You mean when invoking
 |a hyperlink which has no target in the same page, less(1) should
 |transparently invoke apropos(1) to search for it in other manuals?
 |That idea seems bold and interesting, but quite difficult to
 |implement, even more difficult than complete .Ix support.
 |
 |The steps would be:
 |
 | 1. Local .Ix, that is, .Ix for linking within one page.
 |    (Which includes all we have discussed so far.)
 | 2. Let apropos(1) support .Ix, that is, allow searching
 |    for macro keys having the .Ix property.
 | 3. Let step 2 be used from within a manual viewer.
 |
 |Are you jumping to step 3 here?  That would be a jump very far into
 |the future, before even the foundations have been laid.

I agree with that.  And as above.

 |[...]
 |> P.S.: what about a ".To [number]" request that embeds an
 |> automatically created table of contents for all .Sh and .Ss of
 |> a document?  That would also be a real win, but this time
 |> _especially_ for HTML and PDF output..
 |
 |That's useless for almost all manuals because .Sh headers are
 |standardized, some every manual would have almost literally the
 |same table of contents, .Ss are used very little (and rightly so),
 |and most manuals are too short for a table of contents to be useful.

Sure, yet the amount of text in between them varies :).

 |For the very small number of manuals that might profit from such a
 |feature, introducing a new macro isn't warranted, in particular
 |since you can already trivially do this:
 |
 |  $ man ksh | grep '^...[^ ]'

Oh no.  Is it "Line editing", "Line-editing"?  No, it is "In-line
Editing Options."  Ah, would have been easy with a TOC.
Ciao,

--steffen



reply via email to

[Prev in Thread] Current Thread [Next in Thread]