Z shell introductory guide source

Z shell introductory guide source

[Clinton Bunch]

I've been working on a re-org of the web site and I can't find the 
source for the introductory guide.  It doesn't appear to be in the 
zsh-web git repository.  Does someone still have a copy of the texinfo 
source?

Re: Z shell introductory guide source

[Bart Schaefer]

On Sat, Sep 21, 2024 at 7:09 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>
> I've been working on a re-org of the web site and I can't find the
> source for the introductory guide.  It doesn't appear to be in the
> zsh-web git repository.  Does someone still have a copy of the texinfo
> source?

There is no texinfo source.  The source is Doc/intro.ms, which has to
be run through troff or similar.

Re: Z shell introductory guide source

[Clinton Bunch]

On 9/22/2024 12:33, Bart Schaefer wrote:
> On Sat, Sep 21, 2024 at 7:09 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>> I've been working on a re-org of the web site and I can't find the
>> source for the introductory guide.  It doesn't appear to be in the
>> zsh-web git repository.  Does someone still have a copy of the texinfo
>> source?
> There is no texinfo source.  The source is Doc/intro.ms, which has to
> be run through troff or similar.
>
Apparently there was a texinfo version at some point that was used to 
generate the HTML version.  But it has apparently been lost in the void.

Re: Z shell introductory guide source

[Oliver Kiddle]

Clinton Bunch wrote:
> On 9/22/2024 12:33, Bart Schaefer wrote:
> > On Sat, Sep 21, 2024 at 7:09 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
> >> I've been working on a re-org of the web site and I can't find the
> >> source for the introductory guide.  It doesn't appear to be in the
> >> zsh-web git repository.  Does someone still have a copy of the texinfo
> >> source?
> > There is no texinfo source.  The source is Doc/intro.ms, which has to
> > be run through troff or similar.
> >
> Apparently there was a texinfo version at some point that was used to 
> generate the HTML version.  But it has apparently been lost in the void.

Are you talking about Peter's user-friendly user guide. That is in the
zsh-web git repository in Guide/zshguide.tar.gz. That contains Yodl
source files dated 17 May 2014. The current web site probably gives it
too much prominence given it is unmaintained. There have been one or
two occasions where someone has posted corrections to it to the list and
they've either been ignored or applied direct to the HTML.

Paul Falstad's "An Introduction to the Z Shell" is Doc/intro.ms in
original source form for troff. It's not a bad document and processing
it to HTML could be worthwhile.

Oliver

Re: Z shell introductory guide source

[Bart Schaefer]

On Sun, Sep 22, 2024 at 11:40 AM Oliver Kiddle <opk@zsh.org> wrote:
>
> Paul Falstad's "An Introduction to the Z Shell" is Doc/intro.ms in
> original source form for troff. It's not a bad document and processing
> it to HTML could be worthwhile.

I've tried running it through a couple of different groff-based
converters ... it's necessary to pass the -ms option to groff, but
even with that I haven't been able to produce anything as nice as
what's presently formatted on the zsh web pages.  In particular some
of the macro definitions don't appear to work correctly, e.g. this:

.de Sh
.SH
\\$1
.XS
\\$1
.XE
..

produces many ".XS without .XE" errors during processing.

Re: Z shell introductory guide source

[Clinton Bunch]

On 9/22/2024 13:40, Oliver Kiddle wrote:
> Clinton Bunch wrote:
>> On 9/22/2024 12:33, Bart Schaefer wrote:
>>> On Sat, Sep 21, 2024 at 7:09 PM Clinton Bunch <cdb_zsh@zentaur.org> wrote:
>>>> I've been working on a re-org of the web site and I can't find the
>>>> source for the introductory guide.  It doesn't appear to be in the
>>>> zsh-web git repository.  Does someone still have a copy of the texinfo
>>>> source?
>>> There is no texinfo source.  The source is Doc/intro.ms, which has to
>>> be run through troff or similar.
>>>
>> Apparently there was a texinfo version at some point that was used to
>> generate the HTML version.  But it has apparently been lost in the void.
> Are you talking about Peter's user-friendly user guide. That is in the
> zsh-web git repository in Guide/zshguide.tar.gz. That contains Yodl
> source files dated 17 May 2014. The current web site probably gives it
> too much prominence given it is unmaintained. There have been one or
> two occasions where someone has posted corrections to it to the list and
> they've either been ignored or applied direct to the HTML.
>
> Paul Falstad's "An Introduction to the Z Shell" is Doc/intro.ms in
> original source form for troff. It's not a bad document and processing
> it to HTML could be worthwhile.
>
> Oliver
Paul Falstad's "An Introduction to the Z Shell" was apparently processed 
into HTML in '95 and is in the Intro sub-directory.  But it appears to 
have been created using texi2html from a texinfo version that someone 
created by hand.  (I know I read the person's name somewhere, but can't 
find it this morning)  I'm now researching *roff to HTML converters, but 
most seem to be for mandoc rather than ms.

Re: Z shell introductory guide source

[Jun. T]

> 2024/09/23 3:47, Bart Schaefer <schaefer@brasslantern.com> wrote:
> 
> In particular some
> of the macro definitions don't appear to work correctly, e.g. this:
> 
> .de Sh
> .SH
> \\$1
> .XS
> \\$1
> .XE
> ..
> 
> produces many ".XS without .XE" errors during processing.

I think .XS/.XE is for creating the table of contents. But it seems
the current version of groff has an ability to create the TOC
automatically.

If ".XS ... .XE" is removed then

groff -ms -Thtml intro.ms > intro.html

produces a "readable" html, but the font size in the text changes
after examples. So I also removed the '.ps' in .Ds and .De macros
(there may be better solutions, I guess).

In the patch below I also removed the front page. I hope this may
help to get better html.

If we want separate html files for each section:

groff -ms -Thtml -P-jxxx intro.ms > intro.html

this will produce intro.html and xxx-1.html xxx-2.html ...

# the patch is just for producing html, not for intro.pdf.

diff --git a/Doc/intro.ms b/Doc/intro.ms
index 4dd08f601..8d77613b3 100644
--- a/Doc/intro.ms
+++ b/Doc/intro.ms
@@ -8,14 +8,12 @@
 .de Ds
 .DS I .5i
 .ft C
-.ps 9
 .vs 11
 .ss 11
 ..
 .de De
 .DE
 .ft R
-.ps
 .vs
 .ie \n(.g .ss \n(De
 .el .ss
@@ -23,33 +21,7 @@
 .de Sh
 .SH
 \\$1
-.XS
-\\$1
-.XE
 ..
-.nr HM 4i
-.ce 99
-.ps 18
-.vs 20
-.ss 20
-\f3An Introduction to the Z Shell\fP
-
-.ps 14
-.vs 16
-.ss 16
-\f2Paul Falstad
-pf@software.com
-
-Bas de Bakker
-bas@phys.uva.nl\fP
-.ce 0
-.nr HM 1i
-.pn 1
-.bp
-.\" This blank page on the reverse of the cover.
-.sv |1i
-.pn 1
-.bp
 .TL
 An Introduction to the Z Shell
 .AU
@@ -2716,6 +2688,3 @@ me of any errors in this document.
 .bp
 .sv 1i
 .\}
-.pn 1
-.bp
-.PX

Re: Z shell introductory guide source

[Jun T]

> 2024/09/26 20:06, I wrote:
> 
> In the patch below I also removed the front page. I hope this may
> help to get better html.

The patch is broken in the Mailing List Archive; mail addresses are
hidden as pf@xxxxxxxxxxxx.
If you've got the patch from the Archive website then please
correct the two mail addresses pf@xxxxxxxxxxxx and
bas@xxxxxxxxxxx before applying it.

Re: Z shell introductory guide source

[Jun. T]

The patch below has two objectives:

For intro.html:
Almost same as my previous patch. Use conditional ".if \n[HTML]"
so that the same ms file can be used for both pdf and html.
I don't know why we need different macros for html and pdf.

For intro.pdf:
Use -mspdf instead of -ms, and .XN instead of .XS/.XE. This adds an
Index to the pdf that can be accessed via the side panel (side bar)
of PDF viewers (evince, Preview.app, etc.).
-no-kill-null-pages is to retain blank pages after the cover page
and before the TOC; these are useful only for those who actually
print the pdf to double-sided papers.

I will push this if no one has found a better ms->html converter than
groff -ms -Thtml.
# Manpage of grohtml(1) (groff's html driver) says, in the Bugs section,
# "grohtml is still beta code." It may improve in the future, hopefully.


diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index fa2a336ad..318004b64 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -93,7 +93,7 @@ all: man $(runhelp) texi ../META-FAQ
 .PHONY: all
 
 everything: all html info zsh_a4.dvi zsh_us.dvi zsh_a4.pdf zsh_us.pdf \
-            intro.a4.pdf intro.us.pdf
+            intro.a4.pdf intro.us.pdf intro.html
 .PHONY: everything
 
 dvi: zsh.dvi
@@ -121,11 +121,14 @@ zsh.pdf zsh_a4.pdf zsh_us.pdf: $(sdir)/zsh.texi
 intro.pdf intro.a4.pdf intro.us.pdf: $(sdir)/intro.ms
 	if test $@ = intro.us.pdf || \
 	  { test $@ = intro.pdf && test "$(PAPERSIZE)" = us; }; then \
-	  pdfroff -ms -P-pletter $(sdir)/intro.ms > $@; \
+	  pdfroff -mspdf --no-kill-null-pages -P-pletter $< > $@; \
 	else \
-	  pdfroff -ms -P-pa4 $(sdir)/intro.ms > $@; \
+	  pdfroff -mspdf --no-kill-null-pages -P-pa4 $< > $@; \
 	fi
 
+intro.html: $(sdir)/intro.ms
+	groff -ms -Thtml -P-jintro $< > $@
+
 texi: $(sdir)/zsh.texi
 .PHONY: texi
 
diff --git a/Doc/intro.ms b/Doc/intro.ms
index 4dd08f601..49f6cc07f 100644
--- a/Doc/intro.ms
+++ b/Doc/intro.ms
@@ -3,8 +3,32 @@
 .if \n(.g \{\
 .if "\*(.T"ascii" .ftr C R
 .if "\*(.T"latin1" .ftr C R
+.if "\*(.T"html" .nr HTML 1
 .nr De \n[.ss]
 .\}
+.\" ----- macro defintions -----
+.\" Ds/De: start/end of example
+.\" Sh: section header
+.\" XXX: It seems we can't use the same definition for both pdf and html
+.\"      (at least with groff-12.3.0).
+.\"
+.\" for HTML output
+.ie \n[HTML] \{\
+.de Ds
+.DS I .5i
+.ft C
+..
+.de De
+.DE
+.ft R
+..
+.de Sh
+.NH
+\\$1
+..
+.\}
+.\" for other output (such as PDF)
+.el \{\
 .de Ds
 .DS I .5i
 .ft C
@@ -21,12 +45,13 @@
 .el .ss
 ..
 .de Sh
-.SH
-\\$1
-.XS
-\\$1
-.XE
+.NH
+.XN \\$1
 ..
+.\}
+.\"
+.\" ----- Cover page -----
+.if !\n[HTML] \{\
 .nr HM 4i
 .ce 99
 .ps 18
@@ -50,6 +75,9 @@ bas@phys.uva.nl\fP
 .sv |1i
 .pn 1
 .bp
+.\}
+.\"
+.\" ----- main text -----
 .TL
 An Introduction to the Z Shell
 .AU
@@ -2712,6 +2740,7 @@ I (Bas de Bakker) would be happy to receive mail if anyone has any
 tricks or ideas to add to this document, or if there are some points
 that could be made clearer or covered more thoroughly.  Please notify
 me of any errors in this document.
+.if !\n[HTML] \{\
 .if o \{\
 .bp
 .sv 1i
@@ -2719,3 +2748,4 @@ me of any errors in this document.
 .pn 1
 .bp
 .PX
+.\}

Re: Z shell introductory guide source

[Clinton Bunch]

On 10/9/2024 08:14, Jun. T wrote:
> The patch below has two objectives:
>
> For intro.html:
> Almost same as my previous patch. Use conditional ".if \n[HTML]"
> so that the same ms file can be used for both pdf and html.
> I don't know why we need different macros for html and pdf.
>
> For intro.pdf:
> Use -mspdf instead of -ms, and .XN instead of .XS/.XE. This adds an
> Index to the pdf that can be accessed via the side panel (side bar)
> of PDF viewers (evince, Preview.app, etc.).
> -no-kill-null-pages is to retain blank pages after the cover page
> and before the TOC; these are useful only for those who actually
> print the pdf to double-sided papers.
>
> I will push this if no one has found a better ms->html converter than
> groff -ms -Thtml.
> # Manpage of grohtml(1) (groff's html driver) says, in the Bugs section,
> # "grohtml is still beta code." It may improve in the future, hopefully.
>
I have a first-cut at a post-processor for intro.html (I was unable to 
find anything better than grohtml)  The results of the current version 
can be seen at https://zsh.clintonbunch.name/Intro/intro-new.html

I also looked for an HTML to PDF converter that could maintain internal 
links, but didn't come across anything, with an eye to possibly changing 
the format of record of the guide.

Re: Z shell introductory guide source

[Clinton Bunch]

BTW, just realized in my previous e-mail, I forgot to say thanks for 
your work on improving the roff file html output.

On 10/9/2024 08:32, Clinton Bunch wrote:
> On 10/9/2024 08:14, Jun. T wrote:
>> The patch below has two objectives:
>>
>> For intro.html:
>> Almost same as my previous patch. Use conditional ".if \n[HTML]"
>> so that the same ms file can be used for both pdf and html.
>> I don't know why we need different macros for html and pdf.
>>
>> For intro.pdf:
>> Use -mspdf instead of -ms, and .XN instead of .XS/.XE. This adds an
>> Index to the pdf that can be accessed via the side panel (side bar)
>> of PDF viewers (evince, Preview.app, etc.).
>> -no-kill-null-pages is to retain blank pages after the cover page
>> and before the TOC; these are useful only for those who actually
>> print the pdf to double-sided papers.
>>
>> I will push this if no one has found a better ms->html converter than
>> groff -ms -Thtml.
>> # Manpage of grohtml(1) (groff's html driver) says, in the Bugs section,
>> # "grohtml is still beta code." It may improve in the future, hopefully.
>>
> I have a first-cut at a post-processor for intro.html (I was unable to 
> find anything better than grohtml)  The results of the current version 
> can be seen at https://zsh.clintonbunch.name/Intro/intro-new.html
>
> I also looked for an HTML to PDF converter that could maintain 
> internal links, but didn't come across anything, with an eye to 
> possibly changing the format of record of the guide.
>
>

Re: Z shell introductory guide source

[Bart Schaefer]

[-- Attachment #1: Type: text/plain, Size: 333 bytes --]

On Wed, Oct 9, 2024 at 6:15 AM Jun. T <takimoto-j@kba.biglobe.ne.jp> wrote:

>
> For intro.pdf:
> Use -mspdf instead of -ms, and .XN instead of .XS/.XE.
>

Thanks for this.  As long as we're messing with Makefile.in, should we be
checking somewhere that pdfroff is actually available?  Like we do with
yodl, for example.

[-- Attachment #2: Type: text/html, Size: 643 bytes --]

Re: Z shell introductory guide source

[Jun T]

> 2024/10/10 0:04, Bart Schaefer <schaefer@brasslantern.com> wrote:
> 
>   As long as we're messing with Makefile.in, should we be checking somewhere that pdfroff is actually available?  Like we do with yodl, for example.

Currently, if yodl is not available, trying to create zsh.pdf
causes an error, but empty zsh.texi and manpages, almost empty
zsh.info <http://zsh.info/> and index.html are created without errors.

What should we do if pdfroff (or groff) is not available?

Re: Z shell introductory guide source

[Jun. T]

> 2024/10/10 9:53、Jun T <takimoto-j@kba.biglobe.ne.jp>のメール:
> 
> Currently, if yodl is not available, trying to create zsh.pdf
> causes an error, but empty zsh.texi and manpages, almost empty
> zsh.info and index.html are created without errors.

Sorry, these are for not modifying pre-built docs from doc.tar.gz.

Since doc.tar.gz contains intro.{a4,us}.pdf whose time stamps
are newer than intro.ms, 'make pdf' will not try to rebuild
them and the pdf files remains intact even if pdfroff is not
available.
Is this enough? or should we 'touch' the pdf files to make it
sure that the time stamps are newer?

Re: Z shell introductory guide source

[Jun. T]

Sorry for the delay. I slightly modified Doc/Makefie.in
(intro.ms is the same as in the previous post: workers/53137).

'make html' will build both zsh.html and intro.html.

If intro.ms is newer than intro.{pdf,html} and if pdfroff/groff
is not available, 'make intro.{pdf,html}' will fail without
touching intro.{pdf,html} (if they ever exist).


diff --git a/Doc/Makefile.in b/Doc/Makefile.in
index fa2a336ad..a986aa1c5 100644
--- a/Doc/Makefile.in
+++ b/Doc/Makefile.in
@@ -121,9 +121,16 @@ zsh.pdf zsh_a4.pdf zsh_us.pdf: $(sdir)/zsh.texi
 intro.pdf intro.a4.pdf intro.us.pdf: $(sdir)/intro.ms
 	if test $@ = intro.us.pdf || \
 	  { test $@ = intro.pdf && test "$(PAPERSIZE)" = us; }; then \
-	  pdfroff -ms -P-pletter $(sdir)/intro.ms > $@; \
+	  pdfroff -mspdf --no-kill-null-pages -P-pletter --pdf-output=$@ $<; \
 	else \
-	  pdfroff -ms -P-pa4 $(sdir)/intro.ms > $@; \
+	  pdfroff -mspdf --no-kill-null-pages -P-pa4 --pdf-output=$@ $<; \
+	fi
+
+intro.html: $(sdir)/intro.ms
+	if groff -ms -Thtml -P-jintro $< > tmp.html; then \
+	  mv tmp.html $@; \
+	else \
+	  rm -f tmp.html; false; \
 	fi
 
 texi: $(sdir)/zsh.texi
@@ -170,7 +177,7 @@ a4_ps: zsh_a4.ps
 zsh_a4.ps: zsh_a4.dvi
 	$(DVIPS) -t a4 -o $@ zsh_a4.dvi
 
-html: zsh_toc.html
+html: zsh_toc.html intro.html
 .PHONY: html
 
 zsh_toc.html: $(sdir)/zsh.texi texi2html.conf