manual all on one HTML page

manual all on one HTML page

[Dave Yost]

Hi.

There really should be an all-on-one-page HTML manual.

I tried to look for the exec command using the current divided-up 
HTML and couldn't find it.

Thanks

Dave

Re: manual all on one HTML page

[Phil Pennock]

On 2007-04-29 at 17:49 -0700, Dave Yost wrote:
>  There really should be an all-on-one-page HTML manual.
> 
>  I tried to look for the exec command using the current divided-up HTML and 
>  couldn't find it.

Go to your zsh source, into the Doc subdirectory.  Edit "Makefile"
(after configure, etc), find the TEXI2HTML line.

Change:
  TEXI2HTML = texi2html --output . --ifinfo --split=chapter
to:
  TEXI2HTML = texi2html --output zshall.html --ifinfo

Run "make html".

Peruse "zshall.html".

-Phil

Re: manual all on one HTML page

[Dave Yost]

At 07:17 PM -0700 2007-04-29, Phil Pennock wrote:
>On 2007-04-29 at 17:49 -0700, Dave Yost wrote:
>>  There really should be an all-on-one-page HTML manual.
>>
>>  I tried to look for the exec command using the current divided-up HTML and
>>  couldn't find it.
>
>Go to your zsh source, into the Doc subdirectory.  Edit "Makefile"
>(after configure, etc), find the TEXI2HTML line.
>
>Change:
>  TEXI2HTML = texi2html --output . --ifinfo --split=chapter
>to:
>  TEXI2HTML = texi2html --output zshall.html --ifinfo
>
>Run "make html".
>
>Peruse "zshall.html".

Thanks.  It would be handy on the web site, too...

Re: manual all on one HTML page

[Stephane Chazelas]

On Sun, Apr 29, 2007 at 05:49:07PM -0700, Dave Yost wrote:
> Hi.
> 
> There really should be an all-on-one-page HTML manual.
> 
> I tried to look for the exec command using the current divided-up 
> HTML and couldn't find it.
[...]

That's the biggest problem with the HTML format. That's why
there exist more advanced formats like the "info" formats. The
info format is inspired from books. There is a table of content
and an index, both searchable with completion, and the whole
document can be searched as well.

See the "g", "i", "m", "s" keys in info.

Typically:

info zsh
iexec<Tab>

-- 
Stéphane

Re: manual all on one HTML page

[Dave Yost]

At 07:13 AM +0100 2007-04-30, Stephane Chazelas wrote:
>On Sun, Apr 29, 2007 at 05:49:07PM -0700, Dave Yost wrote:
>> Hi.
>>
>> There really should be an all-on-one-page HTML manual.
>>
>> I tried to look for the exec command using the current divided-up
>> HTML and couldn't find it.
>[...]
>
>That's the biggest problem with the HTML format.

The one-page format makes simple searches easy using the browser.

Also: the broken-up HTML is nicely searchable with a Google using the "site:" feature, like this:
  foo site:zsh.org/doc/one-page.html

Dave

>That's why
>there exist more advanced formats like the "info" formats. The
>info format is inspired from books. There is a table of content
>and an index, both searchable with completion, and the whole
>document can be searched as well.
>
>See the "g", "i", "m", "s" keys in info.
>
>Typically:
>
>info zsh
>iexec<Tab>
>
>--
>Stéphane

Re: manual all on one HTML page

[Stephane Chazelas]

On Mon, Apr 30, 2007 at 12:24:41AM -0700, Dave Yost wrote:
> At 07:13 AM +0100 2007-04-30, Stephane Chazelas wrote:
> >On Sun, Apr 29, 2007 at 05:49:07PM -0700, Dave Yost wrote:
> >> Hi.
> >>
> >> There really should be an all-on-one-page HTML manual.
> >>
> >> I tried to look for the exec command using the current divided-up
> >> HTML and couldn't find it.
> >[...]
> >
> >That's the biggest problem with the HTML format.
> 
> The one-page format makes simple searches easy using the browser.

Yes, but makes the browsing (reaching the section you're
interested in) difficult.

> Also: the broken-up HTML is nicely searchable with a Google using the "site:" feature, like this:
>   foo site:zsh.org/doc/one-page.html

Yes, we agree that's the problem, you need some external tool to
index your pages, as HTML has not such thing built in.

The index and search are built in "info". I'd agree the "info"
client command is not the best that one could have come up to,
but at least the "info" format makes it very easy and direct to
reach the information you're looking for.

And zsh has completion support (to some extent) for info.

-- 
Stéphane

Re: manual all on one HTML page

[Dave Yost]

At 09:01 AM +0100 2007-04-30, Stephane Chazelas wrote:
>On Mon, Apr 30, 2007 at 12:24:41AM -0700, Dave Yost wrote:
>> At 07:13 AM +0100 2007-04-30, Stephane Chazelas wrote:
>> >On Sun, Apr 29, 2007 at 05:49:07PM -0700, Dave Yost wrote:
>> >> Hi.
>> >>
>> >> There really should be an all-on-one-page HTML manual.
>> >>
>> >> I tried to look for the exec command using the current divided-up
>> >> HTML and couldn't find it.
>> >[...]
>> >
>> >That's the biggest problem with the HTML format.
>>
>> The one-page format makes simple searches easy using the browser.
>
>Yes, but makes the browsing (reaching the section you're
>interested in) difficult.

Sure, but I'm not suggesting removing the link to the piecewise HTML.  I'm just suggesting adding one little extra link on the web page, to a format that is supported in the downloaded source.

Dave

Re: manual all on one HTML page

[Phil Pennock]

On 2007-04-30 at 09:01 +0100, Stephane Chazelas wrote:
> The index and search are built in "info". I'd agree the "info"
> client command is not the best that one could have come up to,
> but at least the "info" format makes it very easy and direct to
> reach the information you're looking for.

pinfo(1).

"Ncurses based, lynx style info documentation browser"

I switched a while back, it's a great relief.  Almost makes info-doc
browsing painless.

http://pinfo.alioth.debian.org/

-Phil

Re: manual all on one HTML page

[Stephane Chazelas]

On Mon, Apr 30, 2007 at 01:51:42PM -0700, Phil Pennock wrote:
> On 2007-04-30 at 09:01 +0100, Stephane Chazelas wrote:
> > The index and search are built in "info". I'd agree the "info"
> > client command is not the best that one could have come up to,
> > but at least the "info" format makes it very easy and direct to
> > reach the information you're looking for.
> 
> pinfo(1).
> 
> "Ncurses based, lynx style info documentation browser"
> 
> I switched a while back, it's a great relief.  Almost makes info-doc
> browsing painless.
> 
> http://pinfo.alioth.debian.org/
[...]

Last time I checked pinfo had neither of "i" or "g" or "m" or
completions, which are the very features that make info better
than HTML for documentation, so it was pretty useless.

It may have changed since then. ?

-- 
Stéphane