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.