Re: Learning troff - where to start?

[Johann Höchtl]

On 14.10.20 18:41, Peter Schaffter wrote:

On Wed, Oct 14, 2020, Johann Höchtl wrote:

Groff is certainly feature-rich, stable and polished with
great documentation.  But I also value l8n, being able to
input utf8-characters directly into the source or easily
switch fonts.  Not to mention PAO (paragraph-at-once) from
Knuth-Plass.  In that respect both Heirloom and Neatroff are
compelling alternatives and it would be great for mom if she would
be available there too.

I haven't inspected either Heirloom or Neatroff closely so I don't
know how big a job porting would be.  I'm not likely to undertake it
myself, though if anyone wanted to, I'd be more than happy to act as
a go-to resource.


In a personal conversation with Deri James he re-introduced me again to 
the mom macro package. So I gave it a whirl and fed neatroff with mom.


I removed the guards checking for groff and version.


Overall errors (neatroff) were:

neatroff: failed to mount 
neatroff: bad font position 0
neatroff: failed to mount <0>
neatroff: failed to mount <\*[$FONT]>
neatroff: bad font position 0
neatroff: failed to mount <0>
neatroff: failed to mount <\*[$FONT]>

Sounds like recoverable errors of missing fonts. The macro package 
finally failed with


[mom]: Aborting '\n[.F]', line \n[.c].

That sounds rather fatal and even the error message is truncated as I 
think registers, which should keep line numbers or the like, are not set.


Now that particular occurs rather often in mom and I couldn't trace it 
further down. Is there a chance to increase a verbosity level to 
actually see where mom fails?



Best, Johann

Re: Learning troff - where to start?

[Pierre-Jean Fichet]

Hello Johann,

Johann Höchtl wrote:
> Your help would be very appreciated. BTW How comes that section headings 
> work as a forward reference? Can I move with utmac the complete TOC to 
> the frontmatter without using psutils or the likes?

The makefile, in the utmac/demo, runs three passes of roff. During the
first pass, it exports a summary to a temporary file. During the
second pass, the macros S2, S3, S4 and S* load that file and print a
summary. A third pass is needed in case the introduction of the
summaries in the document shifted page numbers.

So, indeed, psutils is not needed. I think it's a good way to do such
things, as page numbers are coherent with that system, compliant with
the french habbit, and it allows the insertion of pdf links in the
summary to navigate within the document.

Cheers,
Pierre-Jean.

Re: Learning troff - where to start?

[Pierre-Jean Fichet]

Hello Johann,

Johann Höchtl wrote:
> .../neatroff/roff  -mu-fonts -mus para.tr | ../neatpost/pdf -pa4 > out.pdf

u-fonts only contains macros shared by all fonts and does nothing by
itself, you should use u-libertine or u-biolinum instead:
roff -mus -mu-libertine para.tr | pdf -pa4 > out.pdf

> neatroff: failed to mount 
> I suspect I have missing fonts or am I missing another utmac - macro 
> inclusion?

You also need to install the linux-libertine font in your system first,
then produce the neatroff font. The makefile of neatroff_make, if
that's what you used, should be able to do that with some adaptation.

If not, you can edit the makefile in the "utmac/neatroff":
BINDIR: the path to neatroff mkfn
FNTDIR: the path to the neatroff font directory
DEVDIR: the path to neatroff devutf directory
OTFDIR: the path to your libertine font (/usr/share/fonts)
FONTS: the names of the various fonts you want to convert.

And you can run:
make fonts

And it should work... Though, please note that I'm not using the
default neatroff_make installation, but a custom one, using the
makefile in utmac/neatroff.

Warm regards,
Pierre-Jean.

Re: Learning troff - where to start?

[Johann Höchtl]

On 21.10.20 22:21, Wim Stockman wrote:

maybe you can start by reading the book.
it has new life on github.
https://github.com/larrykollar/Unix-Text-Processing



Thank you for the link. However I am specifically asking the top-poster 
Pierre-Jean how he achieves the following in his utmac-macro:


https://pjfichet.github.io/utroff/pub/layout-uh.pdf

You see that section references are at the start of the document and I wonder 
how this can be done as, as far as I know, troff is single pass and therefore a 
TOC has to be at the end of a document. In the link I provided you see the TOC 
however at the start and I do not thing a postscript re-arrangement of pages is 
used.


Op wo 21 okt. 2020 om 21:47 schreef Johann Höchtl 
:
On 19.10.20 14:14, Johann Höchtl wrote:

On 15.10.20 16:37, Pierre-Jean Fichet wrote:

To fetch for ideas on how to do this or that, maybe can I also point
to my macros, as they'll work with neatroff too, and implement a lot
of things: https://github.com/pjfichet/utmac/


I installed utmac by downloading it and copying all .tmac - files into
netaroff's tmac directory.

Then I copied para.tr and lorem.tr into the demo directory of neatroff
and executed:


../neatroff/roff  -mu-fonts -mus para.tr | ../neatpost/pdf -pa4 >

out.pdf


(also tried for curiosity with muh and mul)


That creates a workable pdf but produces the following error:


neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 


I suspect I have missing fonts or am I missing another utmac - macro
inclusion?



Your help would be very appreciated. BTW How comes that section headings
work as a forward reference? Can I move with utmac the complete TOC to
the frontmatter without using psutils or the likes?



Best, Johann


Hoping that helps!
Pierre-Jean.

Re: Learning troff - where to start?

[Wim Stockman]

maybe you can start by reading the book.
it has new life on github.
https://github.com/larrykollar/Unix-Text-Processing

Op wo 21 okt. 2020 om 21:47 schreef Johann Höchtl :

>
> On 19.10.20 14:14, Johann Höchtl wrote:
> >
> > On 15.10.20 16:37, Pierre-Jean Fichet wrote:
> >> To fetch for ideas on how to do this or that, maybe can I also point
> >> to my macros, as they'll work with neatroff too, and implement a lot
> >> of things: https://github.com/pjfichet/utmac/
> >>
> >
> > I installed utmac by downloading it and copying all .tmac - files into
> > netaroff's tmac directory.
> >
> > Then I copied para.tr and lorem.tr into the demo directory of neatroff
> > and executed:
> >
> >
> > ../neatroff/roff  -mu-fonts -mus para.tr | ../neatpost/pdf -pa4 >
> out.pdf
> >
> >
> > (also tried for curiosity with muh and mul)
> >
> >
> > That creates a workable pdf but produces the following error:
> >
> >
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> > neatroff: failed to mount 
> >
> >
> > I suspect I have missing fonts or am I missing another utmac - macro
> > inclusion?
> >
> >
> Your help would be very appreciated. BTW How comes that section headings
> work as a forward reference? Can I move with utmac the complete TOC to
> the frontmatter without using psutils or the likes?
>
>
> > Best, Johann
> >
> >> Hoping that helps!
> >> Pierre-Jean.
> >>
> >>
> >>
>
>

Re: Learning troff - where to start?

[Johann Höchtl]

On 19.10.20 14:14, Johann Höchtl wrote:


On 15.10.20 16:37, Pierre-Jean Fichet wrote:

To fetch for ideas on how to do this or that, maybe can I also point
to my macros, as they'll work with neatroff too, and implement a lot
of things: https://github.com/pjfichet/utmac/



I installed utmac by downloading it and copying all .tmac - files into 
netaroff's tmac directory.


Then I copied para.tr and lorem.tr into the demo directory of neatroff 
and executed:



../neatroff/roff  -mu-fonts -mus para.tr | ../neatpost/pdf -pa4 > out.pdf


(also tried for curiosity with muh and mul)


That creates a workable pdf but produces the following error:


neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 


I suspect I have missing fonts or am I missing another utmac - macro 
inclusion?



Your help would be very appreciated. BTW How comes that section headings 
work as a forward reference? Can I move with utmac the complete TOC to 
the frontmatter without using psutils or the likes?




Best, Johann


Hoping that helps!
Pierre-Jean.

UTP 1.1 [was Re: Learning troff - where to start?]

[kollar]

> OK, I’ve put the 1.0 sources up on GitHub: 
> https://github.com/larrykollar/Unix-Text-Processing

Following up: John Gardner and Deri James sent pull requests
to get us up to UTP 1.1, and that’s what is now in main.

Note that you’ll need groff 1.22 or newer to format UTP 1.1,
as it uses -Tpdf. I made a 1.0 branch for anyone who has an
older groff… or recently updated MacOS and hasn’t re-installed
their update. I have a question about that, but I’ll put that (and
a discussion about UTP Revisited) in a separate thread.

— Larry

Re: Learning troff - where to start?

[Johann Höchtl]

On 15.10.20 16:37, Pierre-Jean Fichet wrote:

To fetch for ideas on how to do this or that, maybe can I also point
to my macros, as they'll work with neatroff too, and implement a lot
of things: https://github.com/pjfichet/utmac/



I installed utmac by downloading it and copying all .tmac - files into 
netaroff's tmac directory.


Then I copied para.tr and lorem.tr into the demo directory of neatroff 
and executed:



../neatroff/roff  -mu-fonts -mus para.tr | ../neatpost/pdf -pa4 > out.pdf


(also tried for curiosity with muh and mul)


That creates a workable pdf but produces the following error:


neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 
neatroff: failed to mount 


I suspect I have missing fonts or am I missing another utmac - macro 
inclusion?



Best, Johann


Hoping that helps!
Pierre-Jean.

Re: Learning troff - where to start?

[Larry Kollar]

> On Oct 16, 2020, at 6:49 PM, Deri  wrote:
> 
> On Friday, 16 October 2020 04:23:21 BST Larry Kollar wrote:
>>> There is a version with clickable contents and index here:-
>>> 
>>> https://github.com/DeriJames/UTP-1.1/raw/master/utp_book.pdf
>> 
>> Oh, cool. I vaguely remember you doing that.
>> 
>> Maybe we should throw our sources onto Github?
> 
> Hi Larry,
> 
> You will find my sources on github here:-
> 
> https://github.com/DeriJames/UTP-1.1
> 
> I'm very happy if you want to merge my changes with your original work and 
> then upload it to 
> github, I would then delete my repository. I think it is important it remains 
> as your baby since my 
> efforts are minor compared to all the people who did the real work.

OK, I’ve put the 1.0 sources up on GitHub: 
https://github.com/larrykollar/Unix-Text-Processing

The README is a more focused version of the original index page on windstream,
and the PDF is under Releases. I made a couple typo fixes that were flagged
and patiently waiting in my inbox before uploading.

If we start in on UTP Revisited, I think we should redo the macros so Heirloom
and Neatroff users can join the fun. I hope most of it is a matter of “.ie g / 
.el”
blocks.

— Larry

Re: Learning troff - where to start?

[Jan Stary]

On Oct 14 12:41:35, pe...@schaffter.ca wrote:
> What difficulties do you have entering UTF8 directly into the
> source?  I've produced groff documents in most of the Western
> European and Scandinavian languages with direct UTF8 input.  Are
> your troubles with languages other than those?

For instance, Czech UTF8 input (attached), will come out as garbage.

groff -Tps   text.t > text.ps
groff -Tpdf  text.t > text.pdf
groff -Tutf8 text.t > text.utf8

AFAIK, the input has to be preprocessed by preconv(1),
invoked by groff -k; is that what you meant? Then

groff -k -Tutf8 text.t > text.utf8

outputs the input, while

groff -k -Tps   text.t > text.ps
groff -k -Tpdf  text.t > text.pdf

complain about

troff: text.t:1: warning: can't find special character 'u0072_030C'

- I probably miss the fonts that groff would use for these characters.

Anyway, UTF8 is UTF8; I don't understand why there would be a difference
for this or that language, if UTF8 covers characters of both.

Jan



text.t
Description: Troff document

Re: Learning troff - where to start?

[Deri]

On Friday, 16 October 2020 04:23:21 BST Larry Kollar wrote:
> > There is a version with clickable contents and index here:-
> > 
> > https://github.com/DeriJames/UTP-1.1/raw/master/utp_book.pdf
> 
> Oh, cool. I vaguely remember you doing that.
> 
> Maybe we should throw our sources onto Github?

Hi Larry,

You will find my sources on github here:-

https://github.com/DeriJames/UTP-1.1

I'm very happy if you want to merge my changes with your original work and then 
upload it to 
github, I would then delete my repository. I think it is important it remains 
as your baby since my 
efforts are minor compared to all the people who did the real work.

If I had to do all that typing (well using dasher) we would probably still be 
waiting!

Cheers 

Deri

Re: Learning troff - where to start?

[John Gardner]

>
> Maybe we should throw our sources onto Github?


Please do.

On Fri, 16 Oct 2020 at 14:23, Larry Kollar  wrote:

>
> Deri  wrote:
>
> > The UTP Revival Project recreated the source code because Tim and
> > Sale
> >> were unable to locate a copy of the original source. It is located at:
> >>
> >>http://home.windstream.net/kollar/utp/
> >
> >
> > There is a version with clickable contents and index here:-
> >
> > https://github.com/DeriJames/UTP-1.1/raw/master/utp_book.pdf
>
> Oh, cool. I vaguely remember you doing that.
>
> Maybe we should throw our sources onto Github?
>
> — Larry
>

Re: Learning troff - where to start?

[Larry Kollar]

Deri  wrote:

> The UTP Revival Project recreated the source code because Tim and 
> Sale
>> were unable to locate a copy of the original source. It is located at:
>> 
>>http://home.windstream.net/kollar/utp/
> 
> 
> There is a version with clickable contents and index here:-
> 
> https://github.com/DeriJames/UTP-1.1/raw/master/utp_book.pdf

Oh, cool. I vaguely remember you doing that.

Maybe we should throw our sources onto Github?

— Larry

Re: Learning troff - where to start?

[Larry Kollar]

Damian McGuckin  wrote:
> 
> The UTP Revival Project recreated the source code because Tim and Sale were 
> unable to locate a copy of the original source. It is located at:
> 
>   http://home.windstream.net/kollar/utp/
> 
> What an undertaking!
> 
> There is a sentence on that page
> 
>   ... we hope to modernize the book later on.
> 
> If only I had the time.

Oh crap, I just remembered, Windstream says the websites are going away at the 
end of the month. I’ll move the whole thing to my other website and post a link.

So get it while the getting’s good!

— Larry

Re: Learning troff - where to start?

[Federico Lucifredi]

Hi James

> On Oct 14, 2020, at 12:08 PM, James K. Lowden  
> wrote:
> 
> On Wed, 14 Oct 2020 11:13:39 -0400
> Federico Lucifredi  wrote:
> 
>>> For man pages, what you need is knowledge of the man macro package,
>>> originally written by James Clark [...]
>> 
>> I removed the ?originally? bit, which I believe corrects the flaw (if
>> I am reading you correctly). 
> 
> If I may, why not just strike the whole phrase?  For your purpose, does
> it matter who wrote the man macros?  That information is easily
> obtained directly from the groff documentation.  
> 
> groff is written in C++, designed by Bjarne Stroustrup of Bell Labs ….

:-). we are editing a 10-year-old blog, the exercise has reached diminishing 
returns. I wanted to correct the flaw Ingo pointed out, as it could be read to 
imply something factually incorrect (creator vs implementor), but otherwise I 
feel like it is better to leave old writings as immutable and pen new ones. 

> --jkl
> 

Best -F2

Re: Learning troff - where to start?

[Pierre-Jean Fichet]

Hello alls,

I'm a neatroff user, and feels, as a result, compelled to give my
opinion. I'll second everyone stating that "Nroff/Troff User Manual"
(CSTR 54) is the manual of choice. It's 37 pages of well written
documentation, and should cover all your needs:
https://www.troff.org/54.pdf

Then, you'll need to know what are the differences between the old
troff and neatroff:
http://litcave.rudi.ir/neatroff.pdf
http://litcave.rudi.ir/neatstart.pdf

If you use preprocessors (refer, pic, tbl...), you'll have to read
their documentation separately.

Then, if you want to write your own macros, you'll probably want to
begin by adapting one of them, and get used with its internals.
Maybe ms is a good candidate, as it's quite short, and yet used that
way by Ali Gholami Rudi for neatroff, with:
https://github.com/aligrudi/neatroff_make/tree/master/demo
and https://github.com/aligrudi/neatroff_ths

To fetch for ideas on how to do this or that, maybe can I also point
to my macros, as they'll work with neatroff too, and implement a lot
of things: https://github.com/pjfichet/utmac/

I figured that despite appearing unreadable at first glance, the troff
formatting language is easy. I quickly could have my first working
layout. Then comes the harder part of the work when complexity
increases the risk of glitches, and glitches become harder to track
and fix. But in the end, the journey is worth the effort, imho.

Hoping that helps!
Pierre-Jean.

Re: Learning troff - where to start?

[Damian McGuckin]

On Wed, 14 Oct 2020, Mike Bianchi wrote:


Isn't it sad that nothing more modern is available?


Since it is open source,
it might make sense to have a team produce a groff version?


I did follow up with that site. In case you missed it:

 http://home.windstream.net/kollar/utp/

And Deri provided his copy of the PDF with clickable contents and index 
page.



Regards - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[Thomas Dupond]

Peter Schaffter did make this shell script for font installation available on 
his website :

http://schaffter.ca/mom/mom-05.html#install-font

Regards, Thomas


‐‐‐ Original Message ‐‐‐
Le mercredi, octobre 14, 2020 8:16 PM, Johann Höchtl  
a écrit :

>
>
> On 14.10.20 18:41, Peter Schaffter wrote:
>
> > Also not sure what
> > you mean by "easily switch fonts." Since '.ft " is as easy as
> > it gets, I assume you mean something else.
>
> I have been imprecise. By switching fonts I actually meant making fonts
> available to groff, which requires fontforge to generate the Type1 font
> and metrics and then afmtodit.
>
> Best, Johann

Re: Learning troff - where to start?

[Johann Höchtl]

On 14.10.20 18:41, Peter Schaffter wrote:


   Also not sure what
you mean by "easily switch fonts."  Since '.ft " is as easy as
it gets, I assume you mean something else.

I have been imprecise. By switching fonts I actually meant making fonts 
available to groff, which requires fontforge to generate the Type1 font 
and metrics and then afmtodit.



Best, Johann

Re: Learning troff - where to start?

[Steffen Nurpmeso]

Morten Bo Johansen wrote in
 :
 |On 2020-10-14 Peter Schaffter wrote:
 |
 |> What difficulties do you have entering UTF8 directly into the
 |> source?  I've produced groff documents in most of the Western
 |> European and Scandinavian languages
 |
 |I thought we Scandinavians were also considered part of Western
 |Europe, including our languages?
 |
 |;-)

Finnish is definetely not as far as i know, and some people count
Finland to Scandinavia.

--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: Learning troff - where to start?

[Morten Bo Johansen]

On 2020-10-14 Peter Schaffter wrote:

> What difficulties do you have entering UTF8 directly into the
> source?  I've produced groff documents in most of the Western
> European and Scandinavian languages

I thought we Scandinavians were also considered part of Western
Europe, including our languages?

;-)

 Morten

Re: Learning troff - where to start?

[Peter Schaffter]

On Wed, Oct 14, 2020, Johann Höchtl wrote:
> Groff is certainly feature-rich, stable and polished with
> great documentation.  But I also value l8n, being able to
> input utf8-characters directly into the source or easily
> switch fonts.  Not to mention PAO (paragraph-at-once) from
> Knuth-Plass.  In that respect both Heirloom and Neatroff are
> compelling alternatives and it would be great for mom if she would
> be available there too.

I haven't inspected either Heirloom or Neatroff closely so I don't
know how big a job porting would be.  I'm not likely to undertake it
myself, though if anyone wanted to, I'd be more than happy to act as
a go-to resource.

What difficulties do you have entering UTF8 directly into the
source?  I've produced groff documents in most of the Western
European and Scandinavian languages with direct UTF8 input.  Are
your troubles with languages other than those?  Also not sure what
you mean by "easily switch fonts."  Since '.ft " is as easy as
it gets, I assume you mean something else.

-- 
Peter Schaffter
https://www.schaffter.ca

Re: Learning troff - where to start?

[James K. Lowden]

On Wed, 14 Oct 2020 11:13:39 -0400
Federico Lucifredi  wrote:

> >  For man pages, what you need is knowledge of the man macro package,
> >  originally written by James Clark [...]
> 
> I removed the ?originally? bit, which I believe corrects the flaw (if
> I am reading you correctly). 

If I may, why not just strike the whole phrase?  For your purpose, does
it matter who wrote the man macros?  That information is easily
obtained directly from the groff documentation.  

groff is written in C++, designed by Bjarne Stroustrup of Bell Labs 

--jkl

Re: Learning troff - where to start?

[Federico Lucifredi]

Hello Ingo,

> On Oct 14, 2020, at 9:06 AM, Ingo Schwarze  wrote:
> [..]
> 
>> Interesting. As far as I can tell, the origin of that statement
>> is in man 7 groff_man:
>> http://manpages.ubuntu.com/manpages/trusty/man7/groff_man.7.html
> 
> That document says:
> 
>  DESCRIPTION
>  The man macros used to generate man pages with groff
>  were written by James Clark.
> 
> That is correct.
> 
> You are saying:
> 
>  For man pages, what you need is knowledge of the man macro package,
>  originally written by James Clark [...]
> 
> That is a blatant misrepresentation.

No misrepresentation is intended. Be nice. 

> 
> It is akin to talking about "the C programming language, invented
> by Richard M. Stallman, …"

I removed the “originally” bit, which I believe corrects the flaw (if I am 
reading you correctly). 

Best -F

Re: Learning troff - where to start?

[Ingo Schwarze]

Hi Werner,

Werner LEMBERG wrote on Wed, Oct 14, 2020 at 03:27:24PM +0200:
> Ingo Schwarze wrote:

>> Admittedly, it would be better to also credit the original authors,
>> not only the authors of the GNU reimplementation, as it is done
>> here, for example:
>>
>>   https://mandoc.bsd.lv/man/man.7.html

> Mhmm, my name is missing...

Oops.  That error was introduced in 2012 when man-ext was first
mentioned.  Not sure how that happened and why it was never spotted;
the file an-ext.tmac was always clear about the authorship.
Sorry about it.

Fixed by the commit below, which will be in the next release.

Given that misattributions are awkward, i also regenerated
  https://mandoc.bsd.lv/man/man.7.html
right away.  The following will automatically update tomorrow:
  http://man.openbsd.org/man.7

> Anyway, there are some serious typos on that page, for example
> 
>   MT   Begin a mailto block.  This is a non-standard GNU extension.
>It has the following syntax:
> 
>  .<
>  MT address
>  link description to be shown
>  .<
>  ME

Weird.  Apparently, the CSS file was outdated or incorrectly linked,
not sure which.  The problem went away after regenerating the pages,
probably because they now link the CSS correctly.

Thanks for mentioning the CSS problem, too.

Yours,
  Ingo


Log Message:
---
add missing mention of Werner Lemberg, 
noticed by Werner himself on ;
while here, add missing .An macros

Modified Files:
--
mandoc:
man.7

Revision Data
-
Index: man.7
===
RCS file: /home/cvs/mandoc/mandoc/man.7,v
retrieving revision 1.145
retrieving revision 1.146
diff -Lman.7 -Lman.7 -u -p -r1.145 -r1.146
--- man.7
+++ man.7
@@ -612,8 +612,13 @@ The
 language first appeared as a macro package for the roff typesetting
 system in
 .At v7 .
-It was later rewritten by James Clark as a macro package for groff.
-Eric S. Raymond wrote the extended
+It was later rewritten by
+.An James Clark
+as a macro package for groff.
+.An Eric S. Raymond Aq Mt e...@thyrsus.com
+and
+.An Werner Lemberg Aq Mt w...@gnu.org
+wrote the extended
 .Nm
 macros for groff in 2007.
 The stand-alone implementation that is part of the

Re: Learning troff - where to start?

[Mike Bianchi]

> Isn't it sad that nothing more modern is available?

Since it is open source,
it might make sense to have a team produce a groff version?
Mike

Sent from my Adesso PCK-308UW.

On Wed, Oct 14, 2020 at 10:26:27AM +1100, Greg 'groggy' Lehey wrote:
> On Tuesday, 13 October 2020 at 22:49:03 +0200, J.-J. wrote:
> > Le mardi 13 octobre 2020 � 14:41 +0200, Johann H�chtl a �crit :
> >> * What would be a good starting point (tutorial) into troff and its
> >> core principles?
> >>
> >> * What is the canonical documentation of troff all the existing
> >> implementations seem to derive from and describe their deltas in
> >> their respective documentation?
> >
> > Here is in my opinion the best book on the subject
> > (and it's now  FREE!) :
> >
> > https://www.oreilly.com/openbook/utp/
> 
> An excellent book, and one that I have used a lot.  But nobody can
> claim that it's up-to-date (it predates groff), and there are many
> features in groff that weren't in the troff version described.  Isn't
> it sad that nothing more modern is available?
> 
> Greg
> --
> Sent from my desktop computer.
> Finger g...@lemis.com for PGP public key.
> See complete headers for address and phone numbers.
> This message is digitally signed.  If your Microsoft mail program
> reports problems, please read http://lemis.com/broken-MUA

-- 
 Mike Bianchi
 Foveal Systems

 973 822-2085

 mbian...@foveal.com
 http://www.AutoAuditorium.com
 http://www.FovealMounts.com

Re: Learning troff - where to start?

[Werner LEMBERG]

> Admittedly, it would be better to also credit the original authors,
> not only the authors of the GNU reimplementation, as it is done
> here, for example:
>
>   https://mandoc.bsd.lv/man/man.7.html

Mhmm, my name is missing...

Anyway, there are some serious typos on that page, for example

  MT   Begin a mailto block.  This is a non-standard GNU extension.
   It has the following syntax:

 .<
 MT address
 link description to be shown
 .<
 ME


   Werner

Re: Learning troff - where to start?

[Deri]

On Wednesday, 14 October 2020 03:20:17 BST Damian McGuckin wrote:
> The UTP Revival Project recreated the source code because Tim and 
Sale
> were unable to locate a copy of the original source. It is located at:
> 
> http://home.windstream.net/kollar/utp/


There is a version with clickable contents and index here:-

https://github.com/DeriJames/UTP-1.1/raw/master/utp_book.pdf

Re: Learning troff - where to start?

[Ingo Schwarze]

Hi Federico,

Federico Lucifredi wrote on Wed, Oct 14, 2020 at 08:21:49AM -0400:
> On Oct 14, 2020, at 7:10 AM, Ingo Schwarze  wrote:

>> Finally, there is an obvious, rather serious error.  I do not think
>> misattribution should be taken lightly:
>> 
>>  the man macro package, originally written by James Clark
>> 
>> The correct statement is:
>> 
>>  The man language first appeared as a macro package for the roff
>>  typesetting system in Version 7 AT UNIX.  It was later rewritten
>>  by James Clark as a macro package for groff.
>> 
>> I'm not sure which member(s) of the Bell Labs originally designed
>> and implemented the man(7) macros, but it clearly wasn't James Clark.

> Interesting. As far as I can tell, the origin of that statement
> is in man 7 groff_man:
> http://manpages.ubuntu.com/manpages/trusty/man7/groff_man.7.html

That document says:

  DESCRIPTION
  The man macros used to generate man pages with groff
  were written by James Clark.

That is correct.

You are saying:

  For man pages, what you need is knowledge of the man macro package,
  originally written by James Clark [...]

That is a blatant misrepresentation.

It is akin to talking about "the C programming language, invented
by Richard M. Stallman, ..."

Besides, your statement is also incorrect in so far as for many
projects, what you need is mdoc instead (even though it is true
that the Linux man pages project and several other software projects
still use the old man(7) macros).

Besides, the Ubuntu page you quoted is outdated, with an incomplete
AUTHORS section.  The latest stable groff release (from two years ago)
says:

  AUTHORS
  The GNU version of the man macro package was written by James
  Clark and contributors.  The extension macros were written by
  Werner Lemberg  and Eric S. Raymond .

This text was added in 2017.

Admittedly, it would be better to also credit the original authors,
not only the authors of the GNU reimplementation, as it is done
here, for example:

  https://mandoc.bsd.lv/man/man.7.html

But what the groff_man(7) manual page says is not wrong.

> I have no insight myself on the original authorship,
> just quoting from the manual. 

You are misquoting.

Yours,
  Ingo

Re: Learning troff - where to start?

[Federico Lucifredi]

Hello Ingo,

> On Oct 14, 2020, at 7:10 AM, Ingo Schwarze  wrote:
> 
> Finally, there is an obvious, rather serious error.  I do not think
> misattribution should be taken lightly:
> 
>  the man macro package, originally written by James Clark
> 
> The correct statement is:
> 
>  The man language first appeared as a macro package for the roff
>  typesetting system in Version 7 AT UNIX.  It was later rewritten
>  by James Clark as a macro package for groff.
> 
> I'm not sure which member(s) of the Bell Labs originally designed
> and implemented the man(7) macros, but it clearly wasn't James Clark.

Interesting. As far as I can tell, the origin of that statement is in man 7 
groff_man:

http://manpages.ubuntu.com/manpages/trusty/man7/groff_man.7.html

I have no insight myself on the original authorship, just quoting from the 
manual. 

Best -F

Re: Learning troff - where to start?

[Federico Lucifredi]

Hello Raf,

> 
> Also, when it comes to history of *roff from the UNIX manpages
> angle, this[0] is a good place to visit.
> 
> [0] https://manpages.bsd.lv/history.html
> 

That is awesome, it is one of the best stories of man yet (there was a good 
conference talk a few years back as well, I will look for the link).

For completeness, I will point out history of man on Linux is missing there, 
with Andries Brouwer and myself, as well as Colin Watson and Fabrizio Polacco 
missing in the cast of maintainers.

Thanks for sharing!

Best -F

Re: Learning troff - where to start?

[Johann Höchtl]

Dear Peter,

while I first thought a follow-up question would warrant a separate thread,
now as you mention mom, I feel comfortable not to wander astray.

Of course I discovered mom and wow it looks feature-rich and very polished.
I wonder how big of an effort it would be to make it "portable".

Groff is certainly feature-rich, stable and polished with great
documentation. But I also value l8n, being able to input utf8-characters
directly into the source or easily switch fonts. Not to mention PAO
(paragraph-at-once) from Knuth-Plass. In that respect both Heirloom and
Neatroff are compelling alternatives and it would be great for mom if she
would be available there too.

Best, Johann

Am Mi., 14. Okt. 2020 um 03:10 Uhr schrieb Peter Schaffter <
pe...@schaffter.ca>:

> On Wed, Oct 14, 2020, Damian McGuckin wrote:
> > How many people use features of 'groff' that are not in 'troff'?
>
> The mom macros rely heavily on extensions to groff that were
> implemented during Werner's term.  Since many (most?) new groff
> users these days gravitate towards mom, I'd say quite a lot of
> people rely on those features.
>
> I learned troff entirely from ctsr54.  It is not for nothing that
> it remains the canonical starting point for exploring groff.
>
> Prentice-Hall published _Troff Typesetting for UNIX Systems_
> (Emerson, Paulsel) in 1987.  It's still available online.  It might
> be the very thing the OP is looking for.
>
> --
> Peter Schaffter
> https://www.schaffter.ca
>
>

Re: Learning troff - where to start?

[Ingo Schwarze]

Hi Federico,

Federico Lucifredi via wrote on Tue, Oct 13, 2020 at 08:04:10PM -0400:

> For man page writing, I collected the available resources in this
> blog post a while ago - happy to hear about new resources.

If you are curious about new resources, you could mention the
concept of semantic markup and the mdoc(7) language, which was
new twenty years before you wrote your blog post.

Sure, some people might argue that semantic markup is useless or
evil and physical markup is simply better, though i rarely hear
that opinion.  Sure, some people might argue that some semantic
markup languages are too large and complicated for practical use,
and i definitely make that argument regarding DocBook with its 500
different elements and tens of thousands of nesting rules.  Some
people even make that argument for mdoc(7) with its about seventy
macros.

But advertising an article to "collect *the* available resources"
(emphasis is mine) in 2020 if that artcile does not mention the
possibility of writing manual pages with semantic markup feels
surprising to me.  In particular since the first sentence of the
post gives me the impression that this is not intended as Linux-only
but as community-independent.  For all BSD communities, the information
presented in the article is outdated by about three decades, and
for Illumos, it no longer applies, either.

Finally, there is an obvious, rather serious error.  I do not think
misattribution should be taken lightly:

  the man macro package, originally written by James Clark

The correct statement is:

  The man language first appeared as a macro package for the roff
  typesetting system in Version 7 AT UNIX.  It was later rewritten
  by James Clark as a macro package for groff.

I'm not sure which member(s) of the Bell Labs originally designed
and implemented the man(7) macros, but it clearly wasn't James Clark.

Yours,
  Ingo

> https://f2.svbtle.com/writing-man-pages

Re: Learning troff - where to start?

[Ingo Schwarze]

Hi,

Damian McGuckin wrote on Wed, Oct 14, 2020 at 11:41:59AM +1100:
> On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:

>> But that brings us back to where we came in: where is there
>> well-structured documentation for the current groff?

> Agreed.  It is not there.

I wonder where this myth is coming from.

It is here, generated from the texinfo sources:

  https://www.gnu.org/software/groff/manual/html_node/

For groff itself, this is excellent documentation with respect to
completeness, precision, structure, and indexing.

Some specific macro packages are documented in additional documents,
for example manual pages and HTML files, which are also of good
quality.

Yes, there are details that can be polished, and Branden is working
on that.  If you feel bored, you can also start quibbles regarding
the choice of markup language.  But the big picture is that groff
documentation is in better shape than the documentation of many
other software packages.

Given the size and complexity of groff, new users might wish to
read a simpler document first, for example CSTR#54, or another
classical text, several of which were mentioned, just like a newbie
to the C programming language might still use Kernighan/Richie to
get an initial understanding what the basic ideas of the language
are.

But none of that means groff isn't properly documented, and it
doesn't feel helpful to me conveying such an impression when new
users ask questions.

Yours,
  Ingo

Re: Learning troff - where to start?

[Damian McGuckin]

While we are on this topic, anyone know where there is a copy of

Writers Workbench

Thanks - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[John Gardner]

>
> The UTP Revival Project recreated the source code because Tim and Sale
> were unable to locate a copy of the original source.


Does anybody know of a similar effort to recreate the source code of the
last revision of CSTR #54? (November 1992).


On Wed, 14 Oct 2020 at 13:20, Damian McGuckin  wrote:

> On Wed, 14 Oct 2020, Damian McGuckin wrote:
>
> > Would O'Reilly release the source code of the book so it could be
> updated?
>
> The UTP Revival Project recreated the source code because Tim and Sale
> were unable to locate a copy of the original source. It is located at:
>
> http://home.windstream.net/kollar/utp/
>
> What an undertaking!
>
> There is a sentence on that page
>
> ... we hope to modernize the book later on.
>
> If only I had the time.
>
> Regards - Damian
>
> Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
> Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted
> here
> Views & opinions here are mine and not those of any past or present
> employer
>
>

Re: Learning troff - where to start?

[John Gardner]

>
> I learned troff entirely from ctsr54.  It is not for nothing that
> it remains the canonical starting point for exploring groff.


I strongly second this. Newcomers should at least be comfortable changing
fonts, adjusting margins, and controlling paragraph filling/adjustment.
Then they'll move on to macros, strings, and registers. After that, the
difference between macros and requests will be obvious; Users will also
realise why macro packages are there in the first place — the Roff language
is too cumbersome for everyday document preparation.

When I first learned to use Groff, I was confused over the differences
between .Sh / .SH, .TH / .Dt, .B / \fB … "overlapping" features I assumed
were all part of the same opaque format (one designed specifically for man
page display). Now, had I started with CSTR #54 instead of man page
tutorials , I might've learned early on that
Troff *isn't* merely simply a backend for man(1), that man(7) and mdoc(7)
are exclusive of each other, and tbl(1) markup *wasn't* part of the Roff
language. Can you imagine how confused I was before I learned about
preprocessors?

IMHO, mastering Troff is less about knowing what each part does, and more
about where/how each part fits with everything else.





On Wed, 14 Oct 2020 at 12:10, Peter Schaffter  wrote:

> On Wed, Oct 14, 2020, Damian McGuckin wrote:
> > How many people use features of 'groff' that are not in 'troff'?
>
> The mom macros rely heavily on extensions to groff that were
> implemented during Werner's term.  Since many (most?) new groff
> users these days gravitate towards mom, I'd say quite a lot of
> people rely on those features.
>
> I learned troff entirely from ctsr54.  It is not for nothing that
> it remains the canonical starting point for exploring groff.
>
> Prentice-Hall published _Troff Typesetting for UNIX Systems_
> (Emerson, Paulsel) in 1987.  It's still available online.  It might
> be the very thing the OP is looking for.
>
> --
> Peter Schaffter
> https://www.schaffter.ca
>
>

Re: Learning troff - where to start?

[Damian McGuckin]

On Wed, 14 Oct 2020, Damian McGuckin wrote:


Would O'Reilly release the source code of the book so it could be updated?


The UTP Revival Project recreated the source code because Tim and Sale 
were unable to locate a copy of the original source. It is located at:


http://home.windstream.net/kollar/utp/

What an undertaking!

There is a sentence on that page

... we hope to modernize the book later on.

If only I had the time.

Regards - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[Damian McGuckin]

On Tue, 13 Oct 2020, Peter Schaffter wrote:


On Wed, Oct 14, 2020, Damian McGuckin wrote:

How many people use features of 'groff' that are not in 'troff'?


The mom macros rely heavily on extensions to groff that were implemented 
during Werner's term.  Since many (most?) new groff users these days 
gravitate towards mom, I'd say quite a lot of people rely on those 
features.


Sorry, I was unclear. They 'rely' on them. And guru's like yourself 'use' 
them. My question should have been


how many people directly 'use' features


Aren't those extensions hidden behind/under your excellent 'mom'?  Does 
your average user really need to learn underlying 'groff'. My 2c.


I learned troff entirely from ctsr54.  It is not for nothing that it 
remains the canonical starting point for exploring groff.


I have educated quite a few people to use groff by concentrating solely
on the interface that the Macros (and TBL and EQN) present. I did a 
tutorial document of how to use Troff/MM.  If I get some time, I might 
hack it to use MoM. The only groff commands it used were '.br', '.sp'

and '.so'.


Prentice-Hall published _Troff Typesetting for UNIX Systems_
(Emerson, Paulsel) in 1987.  It's still available online.  It might
be the very thing the OP is looking for.


That reminds me I need to get Gehani's two volumes before they disappear 
from the face of the earth.


Regards - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[Peter Schaffter]

On Wed, Oct 14, 2020, Damian McGuckin wrote:
> How many people use features of 'groff' that are not in 'troff'?

The mom macros rely heavily on extensions to groff that were
implemented during Werner's term.  Since many (most?) new groff
users these days gravitate towards mom, I'd say quite a lot of
people rely on those features.

I learned troff entirely from ctsr54.  It is not for nothing that
it remains the canonical starting point for exploring groff.

Prentice-Hall published _Troff Typesetting for UNIX Systems_
(Emerson, Paulsel) in 1987.  It's still available online.  It might
be the very thing the OP is looking for. 

-- 
Peter Schaffter
https://www.schaffter.ca

Re: Learning troff - where to start?

[Tadziu Hoffmann]

> About the only thing I like about Tex better is it does
> multiple passes so you can do forward references.
> Troff makes that hard but it is doable.

I don't think TeX actually does that by itself.  *You* have
to call TeX multiple times.

Forward references work by writing the required information
to an external file (e.g., for LaTeX the .aux file), which
is read when the manuscript is processed a further time.

With groff, you can also use a macro package that does
something similar, so I think there is no fundamental
difference in this regard.

Re: Learning troff - where to start?

[Damian McGuckin]

On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:


On Wednesday, 14 October 2020 at 11:12:26 +1100, Damian McGuckin wrote:

On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:


I do, notably the PostScript display requests.


If you mean the

\X'ps: file '

OK. Point taken although older troff could handle that also from
memory.  But it is so long ago, I cannot remember how.


Yes, that's the way it is for me too.  I wrote the macros about 25
years ago for "The Complete FreeBSD", and I haven't looked at them in
over 10 years.  I did today, and I found it a real rat's nest of
documentation.  Strangely the macro code was much more readable.  But
that brings us back to where we came in: where is there
well-structured documentation for the current groff?


Agreed.  It is not there.

Maybe the old O'Reilly book needs a revision?

Would O'Reilly release the source code of the book so it could be updated?

I wrote a book on how to write reports using troff with MM. I then started 
writing my own book in 1985 on Troff and the various preprocessors but as 
soon as I saw UTP, gave up.


I liked 'lout'. Very clean. Jeffrey Kingstonm was just down the road from 
the office. Smart guy.


Regards - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[Larry McVoy]

I'd like to second this sentiment.  Learning troff itself is for people
who want to write macro package[s].  If you just want to format stuff,
you pick a macro package and learn that.

Personally, I've tried -ms, then tried -me, I went back to -ms.
-ms covers most of the bases and it is pretty simple to learn.  I think
there is another Larry here who did a -mom macro package that people like,
I've not tried that, I'd push you towards -ms and -mom.  And if you are
writing man pages, like Federico said, -man.

The O'Reilly book is still useful because it covers, I believe, all the
preprocessors, pic, tbl, eqn, maybe grap, and that's where you should
be putting some learning energy.

Have fun with roff, it is a *great* system.  I've been program committee
chair for Linux expo back in the day (all that meant was I formatted all
the papers into the proceedings), this was back in 1999 and mostly people
used Tex.  I encouraged people to try troff and the people that did came
back to me say "Wow, this is so easy and the formatting is so fast".  Yes
it is.

About the only thing I like about Tex better is it does multiple passes
so you can do forward references.  Troff makes that hard but it is doable.

Have fun!  Ask questions, we'll answer.

On Tue, Oct 13, 2020 at 08:04:10PM -0400, Federico Lucifredi via wrote:
> Hi Johann,
>   If you confined yourself to writing man pages, you do not need to learn the 
> whole of Troff, and you can limit yourself to a more friendly subset ??? and 
> copying from the many examples found on a *nix system surely helps ;-)
> 
>   For man page writing, I collected the available resources in this blog post 
> a while ago ??? happy to hear about new resources.
> 
> https://f2.svbtle.com/writing-man-pages
> 
> Best-F
> 
> > On Oct 13, 2020, at 8:41 AM, Johann H??chtl  
> > wrote:
> > 
> > Hi,
> > 
> > I am just a casual dabbler who is somehow fascinated by text processing
> > 
> > 
> > I am using neatroff - It seems to be the most actively developed and has 
> > some nice modern features like paragraph-at-once formatting and utf8 
> > support out of the box.
> > 
> > 
> > Having said that, it seems that all troff implementations like plan9 troff 
> > or groff itself, seem to have no canonical, "all-encontained" 
> > documentation. All seems to derive from .. ?
> > 
> > 
> > So my question is:
> > 
> > * What would be a good starting point (tutorial) into troff and its core 
> > principles?
> > 
> > * What is the canonical documentation of troff all the existing 
> > implementations seem to derive from and describe their deltas in their 
> > respective documentation?
> > 
> > 
> > Thank you!
> > 
> > 
> > 
> > 

-- 
---
Larry McVoy  lm at mcvoy.com 
http://www.mcvoy.com/lm 

Re: Learning troff - where to start?

[Raf Czlonka]

On Wed, Oct 14, 2020 at 01:04:10AM BST, Federico Lucifredi via wrote:
> Hi Johann,
>   If you confined yourself to writing man pages, you do not need to learn the 
> whole of Troff, and you can limit yourself to a more friendly subset — and 
> copying from the many examples found on a *nix system surely helps ;-)
> 
>   For man page writing, I collected the available resources in this blog post 
> a while ago — happy to hear about new resources.
> 
> https://f2.svbtle.com/writing-man-pages
> 
> Best-F
> 

Also, when it comes to history of *roff from the UNIX manpages
angle, this[0] is a good place to visit.

[0] https://manpages.bsd.lv/history.html

Regards,

Raf

Re: Learning troff - where to start?

[Greg 'groggy' Lehey]

On Wednesday, 14 October 2020 at 11:12:26 +1100, Damian McGuckin wrote:
> On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:
>
>> I do, notably the PostScript display requests.
>
> If you mean the
>
>   \X'ps: file '
>
> OK. Point taken although older troff could handle that also from
> memory.  But it is so long ago, I cannot remember how.

Yes, that's the way it is for me too.  I wrote the macros about 25
years ago for "The Complete FreeBSD", and I haven't looked at them in
over 10 years.  I did today, and I found it a real rat's nest of
documentation.  Strangely the macro code was much more readable.  But
that brings us back to where we came in: where is there
well-structured documentation for the current groff?

Greg
--
Sent from my desktop computer.
Finger g...@lemis.com for PGP public key.
See complete headers for address and phone numbers.
This message is digitally signed.  If your Microsoft mail program
reports problems, please read http://lemis.com/broken-MUA


signature.asc
Description: PGP signature

Re: Learning troff - where to start?

[Larry McVoy]

So one thing I use a lot is something I got James to add to pic, the
`i'th last thing.   Here is some actual pic source where I used that:

for i = 1 to units by 1 do {
line <-> dashed from `i'th [].C.s - (.10, 0) to \
last box.nw + (i/(units+1)*w, 0)
}

As you may know, you can place stuff relative to a previous thing.
I had a need for being able to place a list of things, place another
list of things and draw lines between the two lists.  Pictures are
worth a thousand words, the .pdf here is done via the .pic here.
You change the units variable and it will draw more or less.

http://mcvoy.com/lm/pic

For differences between troff and groff

man groff_diff

There are differences in there that are a distinct improvement on the
original troff, I use them.  Groff is a better troff.

On Wed, Oct 14, 2020 at 10:36:45AM +1100, Damian McGuckin wrote:
> On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:
> 
> >An excellent book, and one that I have used a lot.  But nobody can claim
> >that it's up-to-date (it predates groff), and there are many features in
> >groff that weren't in the troff version described.  Isn't it sad that
> >nothing more modern is available?
> 
> How many people use features of 'groff' that are not in 'troff'?
> 
> We use groff with MM for half our corporate reports, i.e. those that are not
> mandated as Word, and all our (computer generated) invoices and P/Os, and we
> use no groff specific features as far as I know. And have for 30+ years.
> 
> Regards - Damian
> 
> Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
> Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
> Views & opinions here are mine and not those of any past or present employer

-- 
---
Larry McVoy  lm at mcvoy.com 
http://www.mcvoy.com/lm 

Re: Learning troff - where to start?

[Federico Lucifredi via]

Hi Johann,
  If you confined yourself to writing man pages, you do not need to learn the 
whole of Troff, and you can limit yourself to a more friendly subset — and 
copying from the many examples found on a *nix system surely helps ;-)

  For man page writing, I collected the available resources in this blog post a 
while ago — happy to hear about new resources.

https://f2.svbtle.com/writing-man-pages

Best-F

> On Oct 13, 2020, at 8:41 AM, Johann Höchtl  wrote:
> 
> Hi,
> 
> I am just a casual dabbler who is somehow fascinated by text processing
> 
> 
> I am using neatroff - It seems to be the most actively developed and has some 
> nice modern features like paragraph-at-once formatting and utf8 support out 
> of the box.
> 
> 
> Having said that, it seems that all troff implementations like plan9 troff or 
> groff itself, seem to have no canonical, "all-encontained" documentation. All 
> seems to derive from .. ?
> 
> 
> So my question is:
> 
> * What would be a good starting point (tutorial) into troff and its core 
> principles?
> 
> * What is the canonical documentation of troff all the existing 
> implementations seem to derive from and describe their deltas in their 
> respective documentation?
> 
> 
> Thank you!
> 
> 
> 
> 

Re: Learning troff - where to start?

[Damian McGuckin]

On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:


I do, notably the PostScript display requests.


If you mean the

\X'ps: file '

OK. Point taken although older troff could handle that also from memory.
But it is so long ago, I cannot remember how. That was in the days when
the Postscript output from troff was far more readable.

Regards - Damian

Pacific Engineering Systems International, 277-279 Broadway, Glebe NSW 2037
Ph:+61-2-8571-0847 .. Fx:+61-2-9692-9623 | unsolicited email not wanted here
Views & opinions here are mine and not those of any past or present employer

Re: Learning troff - where to start?

[Greg 'groggy' Lehey]

On Wednesday, 14 October 2020 at 10:36:45 +1100, Damian McGuckin wrote:
> On Wed, 14 Oct 2020, Greg 'groggy' Lehey wrote:
>
>> An excellent book, and one that I have used a lot.  But nobody can claim
>> that it's up-to-date (it predates groff), and there are many features in
>> groff that weren't in the troff version described.  Isn't it sad that
>> nothing more modern is available?
>
> How many people use features of 'groff' that are not in 'troff'?

I do, notably the PostScript display requests.

Greg
--
Sent from my desktop computer.
Finger g...@lemis.com for PGP public key.
See complete headers for address and phone numbers.
This message is digitally signed.  If your Microsoft mail program
reports problems, please read http://lemis.com/broken-MUA


signature.asc
Description: PGP signature

Re: Learning troff - where to start?

[Steffen Nurpmeso]

Greg 'groggy' Lehey wrote in
 <20201013232627.gb24...@eureka.lemis.com>:
 |On Tuesday, 13 October 2020 at 22:49:03 +0200, J.-J. wrote:
 |> Le mardi 13 octobre 2020 à 14:41 +0200, Johann Höchtl a écrit :
 |>> * What would be a good starting point (tutorial) into troff and its
 |>> core principles?
 |>>
 |>> * What is the canonical documentation of troff all the existing
 |>> implementations seem to derive from and describe their deltas in
 |>> their respective documentation?
 |>
 |> Here is in my opinion the best book on the subject
 |> (and it's now  FREE!) :
 |>
 |> https://www.oreilly.com/openbook/utp/
 |
 |An excellent book, and one that I have used a lot.  But nobody can
 |claim that it's up-to-date (it predates groff), and there are many
 |features in groff that weren't in the troff version described.  Isn't
 |it sad that nothing more modern is available?

Ha!  Twenty years ago when my wonderful TeX package got lost and
i had to rapidly implement something and decided due to
frustration to do something entirely different i went to the local
book store (and i still do not do such things over the net), and
they could not offer just about anything.  Solschenizyn, also.
Later.  All that before the advent of on-demand printing, however.

I would point to the groff info manual, and the groff manual
pages.  It is a bit tough to get you going, but if you understand
there are traps and page dimensions then this surely is a starter.
Other than that you need to know what you want, anyway.

Fonts are hard, device files are hard, the process separation is
hard (and a show stopper), but then there is lout and the lua-
implemented thing which appears to be really great and cool,
unfortunately i have forgotten the name of it.  Ralph surely knows
that.

--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: Learning troff - where to start?

[J.-J.]

Hi,

Here is in my opinion the best book on the subject
(and it's now  FREE!) :

https://www.oreilly.com/openbook/utp/

Le mardi 13 octobre 2020 à 14:41 +0200, Johann Höchtl a écrit :
> Hi,
> 
> I am just a casual dabbler who is somehow fascinated by text
> processing
> 
> 
> I am using neatroff - It seems to be the most actively developed and
> has 
> some nice modern features like paragraph-at-once formatting and utf8 
> support out of the box.
> 
> 
> Having said that, it seems that all troff implementations like plan9 
> troff or groff itself, seem to have no canonical, "all-encontained" 
> documentation. All seems to derive from .. ?
> 
> 
> So my question is:
> 
> * What would be a good starting point (tutorial) into troff and its
> core 
> principles?
> 
> * What is the canonical documentation of troff all the existing 
> implementations seem to derive from and describe their deltas in
> their 
> respective documentation?
> 
> 
> Thank you!
> 
> 
> 
> 

Re: Learning troff - where to start?

[Tadziu Hoffmann]

> So my question is:
> 
> * What would be a good starting point (tutorial) into troff
>   and its core principles?
> 
> * What is the canonical documentation of troff all the
>   existing implementations seem to derive from and describe
>   their deltas in their respective documentation?

The answer to both would be the Troff User's Manual, CSTR#54:

  https://www.troff.org/54.pdf

Learning troff - where to start?

[Johann Höchtl]

Hi,

I am just a casual dabbler who is somehow fascinated by text processing


I am using neatroff - It seems to be the most actively developed and has 
some nice modern features like paragraph-at-once formatting and utf8 
support out of the box.



Having said that, it seems that all troff implementations like plan9 
troff or groff itself, seem to have no canonical, "all-encontained" 
documentation. All seems to derive from .. ?



So my question is:

* What would be a good starting point (tutorial) into troff and its core 
principles?


* What is the canonical documentation of troff all the existing 
implementations seem to derive from and describe their deltas in their 
respective documentation?



Thank you!