documentation, texdoc, find, etc + texdist trick from Terminal; was Re: [OS X TeX] OT: low-tech bibliographic hyperlinking

[Roussanka Loukanova]

On Thu, 3 May 2007, Peter Frings wrote:
>
> On May 3, 2007, at 15:08, Roussanka Loukanova wrote:
>
>> roussankas-computer:/usr/local rosi$ find . -name "*biblatex*" -print
>> ./texlive/2007/texmf-doc/doc/english/catalogue/entries/biblatex.html
>> 
>> And then, I copied + pasted
>> 
>> /usr/local/texlive/2007/texmf-doc/doc/english/catalogue/entries/biblatex.html
>> 
>> the browser's address sub-window: File > Open Location...
>
> or simply use the 'open' command in the command line:
> % open ./texlive/2007/texmf-doc/doc/english/catalogue/entries/biblatex.html

Yes, it opens for a fraction of the second.

> To make in independent of the current directory, use '/usr/local' instead of 
> '.'. And you don't need the '-print' option, that's the default action:
> % find /usr/local -name '*biblatex*'

Nice: saves typing.

> You can combine the two using the back-tick trick:
> % open `find /usr/local -name '*biblatex*'`

Yes, it is even better way, but with a tiny correction:

roussankas-computer:/usr/local rosi$ open `find . -name '*biblatex*'`

or, independently of the current dir:

$ open `find /usr/local -name '*biblatex*'`

Double quotes work too.

$ open `find . -name "*biblatex*"`
$ open `find /usr/local -name "*biblatex*"`

>
> or use the -exec option, or pipe the result from find (or anything else) to 
> 'xargs':
> % find /usr/local -name '*biblatex*' | xargs -n 1 open

I can't recall what 'xargs' was (somewhat irritating to see that it 
works without knowing why...

>
>> Isn't there an easier way to get to the TeX catalogue online straight from 
>> the Terminal's command line?
>
> Yes. Use 'texdoc'
>
> % texdoc jurabib
> -> opens 
> /usr/local/teTex/share/texmf.tetex/doc/help/Catalogue/entries/jurabib.html
> texdoc normally looks into the proper locations, and you can configure it a 
> bit with environment variables (e.g. which viewer to use).
>
> % man texdoc
> Usage: texdoc [OPTION]... [NAME]...
> Search for NAME in the TeX documentation and start a viewer.
>
> --help        show this help
> -v            verbose mode: show viewer command
> -l            just list all matching files. Do not start a viewer.
> -s            search the disk. remaining arguments will be passed
>               as egrep patterns to filter the find output.
>

This gives a lot of info to me about how to do: you have on your system 
teTex, and it provides an html link to jurabib documentation.

On my system

roussankas-computer:/usr/local rosi$ texdoc biblatex
Can't find documentation for `biblatex'

I get this response because biblatex is not in my TeX distrs (neither of 
TeXLive 2007 no of gwTeX); and only TeXLive 2007 provides an html link to 
biblatex:

roussankas-computer:/usr/local rosi$ find /usr/local -name "*biblatex*"
/usr/local/texlive/2007/texmf-doc/doc/english/catalogue/entries/biblatex.html

Now, it becomes clear to me that texdoc works only in the currently active 
TeX distr and this is why texdoc can't open the address in the browser.

By having gwTeX as the currently active TeX distr, texdoc doesn't 
open the browser with the html link which is provided only in TeXLive 2007.
And here comes Gerben's texdist abstraction trick in excellent use:

roussankas-computer:/usr/local rosi$ texdist --texdist=TeXLive-2007 'texdoc biblatex'

I get what I am supposed to: Safari opens the TeX catalogue online.

Similarly with jurabib:

jurabib is in both new TeX distrs TeXLive 2005 and gwTeX, but none of them 
provides documentation, while only TeXLive 2005 provides html address.

roussankas-computer:/usr/local rosi$ texdoc jurabib
Can't find documentation for `jurabib'

Again, this is because my currently active TeX distr is gwTeX. With:

roussankas-computer:/usr/local rosi$ texdist --texdist=TeXLive-2007 'texdoc jurabib'

I get what I am supposed to: Safari opens the TeX catalogue online, 
because the only information about documentation in both TeX distrs is:

./texlive/2007/texmf-doc/doc/english/catalogue/entries/jurabib.html

> It work reasonably well if the name of the package and the filename of the 
> documentation are equal. If not you may need the '-s' option (or use locate 
> and grep):
> % texdoc -l beamer
> /usr/local/teTex/share/texmf.tetex/doc/help/Catalogue/entries/beamer.html
> % locate beamer | grep guide
> /usr/local/teTeX/share/texmf.gwtex/doc/latex/beamer/beamerug-guidelines.tex
> /usr/local/teTeX/share/texmf.gwtex/doc/latex/beamer/beameruserguide.pdf
> /usr/local/teTeX/share/texmf.gwtex/doc/latex/beamer/beameruserguide.tex
> /usr/local/teTeX/share/texmf.tetex/doc/latex/beamer/beameruserguide.pdf
> % texdoc -s beamer | grep guide
> /usr/local/teTex/share/texmf.gwtex/doc/latex/beamer/beamerug-guidelines.tex
> /usr/local/teTex/share/texmf.gwtex/doc/latex/beamer/beameruserguide.pdf
> /usr/local/teTex/share/texmf.gwtex/doc/latex/beamer/beameruserguide.tex
> /usr/local/teTex/share/texmf.tetex/doc/latex/beamer/beameruserguide.pdf

Here, I am not quite sure if I entirely understand the details of the 
'-s' option based on what 'texdoc --help' says, and comparing

> Or use google :-)

Yes, we are heading firmly the online direction. But googling is not 
exactly what we need in many cases, in working terms. I think that the 
TeX distrs have created good working environment, in combination with the 
Internet (incl. google, but not yet = google).

Thanks: you've given very good information (at least to me) on getting TeX 
documentation and to the catalogue!

Roussanka

------------------------- Helpful Info -------------------------
Mac-TeX Website: http://www.esm.psu.edu/mac-tex/
TeX FAQ: http://www.tex.ac.uk/faq
List Archive: http://tug.org/pipermail/macostex-archives/
List Reminders & Etiquette: http://www.esm.psu.edu/mac-tex/list/