cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Brian Inglis]

Hi folks, 

Package cygwin-doc files

	/usr/share/doc/cygwin-2.8.0/html/cygwin-{api,ug-net}/*.html 

all contain references to docbook.css: 

	<link rel="stylesheet" type="text/css" href="docbook.css">

but docbook.css is missing from the .../html/cygwin-{api,ug-net}/
directories.

Could you please add docbook.css to the .../html/cygwin-{api,ug-net}/
directories in the cygwin-doc package.

Could you please consider having setup-x86{,_64} install Windows
shortcuts to at least the UG .pdf and index.html if present, in the
.../Start Menu/Programs/Cygwin folder? 
A Windows URL shortcut to https://cygwin.com would also be helpful for
some.

Under .../html/cygwin-{api,ug-net}/ index.html duplicates the contents
of cygwin-{api,ug-net}.html: to avoid duplication, each index.html could
be replaced by a file containing only an HTML "symlink": 

	<meta http-equiv="refresh" content="0;cygwin-api.html">
or
	<meta http-equiv="refresh" content="0;cygwin-ug-net.html">


NIT: Why are these files installed in /usr/share/doc/cygwin-v.r.p/html/,
rather than the expected /usr/share/doc/cygwin/html/, where I would
expect cygwin-doc to install them, and where for some time I have been
downloading and installing my own copies from cygwin.com!

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Corinna Vinschen]

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

On Apr 16 12:22, Brian Inglis wrote:
> Hi folks, 
> 
> Package cygwin-doc files
> 
> 	/usr/share/doc/cygwin-2.8.0/html/cygwin-{api,ug-net}/*.html 
> 
> all contain references to docbook.css: 
> 
> 	<link rel="stylesheet" type="text/css" href="docbook.css">
> 
> but docbook.css is missing from the .../html/cygwin-{api,ug-net}/
> directories.
> 
> Could you please add docbook.css to the .../html/cygwin-{api,ug-net}/
> directories in the cygwin-doc package.

I applied a patch for that.

> Under .../html/cygwin-{api,ug-net}/ index.html duplicates the contents
> of cygwin-{api,ug-net}.html: to avoid duplication, each index.html could
> be replaced by a file containing only an HTML "symlink": 
> 
> 	<meta http-equiv="refresh" content="0;cygwin-api.html">
> or
> 	<meta http-equiv="refresh" content="0;cygwin-ug-net.html">

index.html will be installed as hardlink next time.

> Could you please consider having setup-x86{,_64} install Windows
> shortcuts to at least the UG .pdf and index.html if present, in the
> .../Start Menu/Programs/Cygwin folder? 
> A Windows URL shortcut to https://cygwin.com would also be helpful for
> some.

That requires to change setup or to provide a postinstall script.
Are you willing to provide the latter?


Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Brian Inglis]

On 2017-04-19 04:58, Corinna Vinschen wrote:
> On Apr 16 12:22, Brian Inglis wrote:
>> Package cygwin-doc files
>> 	/usr/share/doc/cygwin-2.8.0/html/cygwin-{api,ug-net}/*.html 
>> all contain references to docbook.css: 
>> 	<link rel="stylesheet" type="text/css" href="docbook.css">
>> but docbook.css is missing from the .../html/cygwin-{api,ug-net}/ 
>> directories.
>> Could you please add docbook.css to the
>> .../html/cygwin-{api,ug-net}/ directories in the cygwin-doc
>> package.
> I applied a patch for that.
>> Under .../html/cygwin-{api,ug-net}/ index.html duplicates the
>> contents of cygwin-{api,ug-net}.html: to avoid duplication, each
>> index.html could be replaced by a file containing only an HTML
>> "symlink":
>> 	<meta http-equiv="refresh" content="0;cygwin-api.html">
>> or
>> 	<meta http-equiv="refresh" content="0;cygwin-ug-net.html">
> index.html will be installed as hardlink next time.

Thank you.

>> Could you please consider having setup-x86{,_64} install Windows 
>> shortcuts to at least the UG .pdf and index.html if present, in
>> the .../Start Menu/Programs/Cygwin folder?
>> A Windows URL shortcut to https://cygwin.com would also be helpful
>> for some.
> That requires to change setup or to provide a postinstall script.
> Are you willing to provide the latter?

I am not aware of any arguments passed to postinstall scripts, so a 
/etc/postinstall/cygwin-doc.sh would have to check for the folders 
"$(cygpath -APU)"/Cygwin or "$(cygpath -PU)"/Cygwin, cd there, 
mkshortcut(s), then cd back, as mkshortcut does not support folders, 
as far as I can tell. 
The postinstall script would also have to run elevated as admin to 
make shortcuts in AllUsers/ProgramData, from what I have found.
An /etc/preremove/cygwin-doc.sh script would also have to be 
provided to remove those shortcuts.
Any problems with that approach or improvements you could suggest?

If I was doing that, I would probably also like to add URL 
shortcuts to the Cygwin page and FAQ. Would that be best done 
by adding .URLs to /usr/share/doc/cygwin-???/ and postinstall 
them in the Start Menu or postinstall mkshortcut(s) to the URLs?

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Jon Turney]

On 19/04/2017 16:42, Brian Inglis wrote:
> On 2017-04-19 04:58, Corinna Vinschen wrote:
>> On Apr 16 12:22, Brian Inglis wrote:
>
>>> Could you please consider having setup-x86{,_64} install Windows
>>> shortcuts to at least the UG .pdf and index.html if present, in
>>> the .../Start Menu/Programs/Cygwin folder?
>>> A Windows URL shortcut to https://cygwin.com would also be helpful
>>> for some.
>> That requires to change setup or to provide a postinstall script.
>> Are you willing to provide the latter?
>
> I am not aware of any arguments passed to postinstall scripts, so a
> /etc/postinstall/cygwin-doc.sh would have to check for the folders
> "$(cygpath -APU)"/Cygwin or "$(cygpath -PU)"/Cygwin, cd there,
> mkshortcut(s), then cd back, as mkshortcut does not support folders,
> as far as I can tell.
> The postinstall script would also have to run elevated as admin to
> make shortcuts in AllUsers/ProgramData, from what I have found.
> An /etc/preremove/cygwin-doc.sh script would also have to be
> provided to remove those shortcuts.
> Any problems with that approach or improvements you could suggest?

This needs documenting, but when running postinstall scripts, Cygwin 
setup sets the CYGWINFORALL env var to "-A" if installing for "All 
Users" [1], for exactly this purpose.

[1] 
https://sourceware.org/git/gitweb.cgi?p=cygwin-setup.git;a=commitdiff;h=c3d07c1372904c915b5895808f2cc6462975901e

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Brian Inglis]

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

On 2017-04-19 15:47, Jon Turney wrote:
> On 19/04/2017 16:42, Brian Inglis wrote:
>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>> On Apr 16 12:22, Brian Inglis wrote:
>>>> Could you please consider having setup-x86{,_64} install Windows
>>>> shortcuts to at least the UG .pdf and index.html if present, in
>>>> the .../Start Menu/Programs/Cygwin folder?
>>>> A Windows URL shortcut to https://cygwin.com would also be helpful
>>>> for some.
>>> That requires to change setup or to provide a postinstall script.
>>> Are you willing to provide the latter?

Darn - hoped you wouldn't ask - attached, and preremove (if not filtered).
Both tested on W10 without, and with CYGWINFORALL=-A and elevated/admin rights.
Comments or improvements you could suggest, or changes you need made?

>> I am not aware of any arguments passed to postinstall scripts, so a
>> /etc/postinstall/cygwin-doc.sh would have to check for the folders
>> "$(cygpath -APU)"/Cygwin or "$(cygpath -PU)"/Cygwin, cd there,
>> mkshortcut(s), then cd back, as mkshortcut does not support folders,
>> as far as I can tell.
>> The postinstall script would also have to run elevated as admin to
>> make shortcuts in AllUsers/ProgramData, from what I have found.
>> An /etc/preremove/cygwin-doc.sh script would also have to be
>> provided to remove those shortcuts.
>> Any problems with that approach or improvements you could suggest?

> This needs documenting, but when running postinstall scripts, Cygwin
> setup sets the CYGWINFORALL env var to "-A" if installing for "All
> Users" [1], for exactly this purpose.
> 
> [1] https://sourceware.org/git/gitweb.cgi?p=cygwin-setup.git;a=commitdiff;h=c3d07c1372904c915b5895808f2cc6462975901e

Thanks Jon - makes things more straightforward.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

[-- Attachment #2: etc.preremove.cygwin-doc.sh --]
[-- Type: text/plain, Size: 571 bytes --]

#!/bin/bash
# /etc/preremove/cygwin-doc.sh - cygwin-doc preremove script.
# removes Cygwin Start Menu shortcuts for Cygwin User Guide and API PDF and
# HTML, and links to Cygwin web site home page and FAQ
#
# CYGWINFORALL=-A if remove for All Users
# remove local shortcuts for All Users or Current User in
# {ProgramData,~/Appdata/Roaming}/Microsoft/Windows/Start Menu/Programs/Cygwin/

cd "$(/bin/cygpath $CYGWINFORALL -P -U)/Cygwin"	|| exit 2

/bin/rm -f -- "User Guide (PDF).lnk" "User Guide (HTML).lnk" \
	"API (PDF).lnk" "API (HTML).lnk" "Home Page.lnk" "FAQ.lnk"


[-- Attachment #3: etc.postinstall.cygwin-doc.sh --]
[-- Type: text/plain, Size: 2018 bytes --]

#!/bin/bash
# /etc/postinstall/cygwin-doc.sh - cygwin-doc postinstall script.
# installs Cygwin Start Menu shortcuts for Cygwin User Guide and API PDF and
# HTML if in doc dir, and links to Cygwin web site home page and FAQ
#
# Assumes you are running setup.exe 2.510.2.2 or newer, executed by /bin/bash 
# and not /bin/[da]sh (if you are running an older setup.exe, this postinstall 
# script can't do anything).
#
# CYGWINFORALL=-A if install for All Users
# installs local shortcuts for All Users or Current User in
# {ProgramData,~/Appdata/Roaming}/Microsoft/Windows/Start Menu/Programs/Cygwin/

cygp=/bin/cygpath
mks=/bin/mkshortcut
un=/bin/uname
site=https://cygwin.com

# check for programs
for p in $un $cygp $mks
do
	if [ ! -x $p ]
	then
		echo "Can't find program '$p'"
		exit 2
	fi
done

cygver=$($un -r)	# release - numeric version (build info)
cygver=${cygver%\(*\)}	# strip build info
doc=/usr/share/doc/cygwin-$cygver
html=$doc/html
smpc_dir="$($cygp $CYGWINFORALL -P -U)/Cygwin"

for d in $doc $html "$smpc_dir"
do
	if [ ! -d "$d/" ]
	then
		echo "Can't find directory '$d'"
		exit 2
	fi
done

if [ ! -w "$smpc_dir/" ]
then
	echo "Can't write to directory '$smpc_dir'"
	exit 1
fi

# mkshortcut works only in current directory - change to Cygwin Start Menu
cd "$smpc_dir" || exit 2	# quit if not found

# User Guide PDF & HTML
p=$doc/cygwin-ug-net.pdf
n="User Guide (PDF)"
d="PDF Cygwin User Guide"

[ -r $p ] && $mks -n "$n" -d "$d" $p 

i=$html/cygwin-ug-net/index.html
n="User Guide (HTML)"
d="HTML Cygwin User Guide"

[ -r $i ] && $mks -n "$n" -d "$d" $i 

# API PDF & HTML
p=$doc/cygwin-api.pdf
n="API (PDF)"
d="PDF Cygwin API Reference"

[ -r $p ] && $mks -n "$n" -d "$d" $p 

i=$html/cygwin-api/index.html
n="API (HTML)"
d="HTML Cygwin API Reference"

[ -r $i ] && $mks -n "$n" -d "$d" $i 

# Home Page URL
h=$site/index.html
n="Home Page"
d="Cygwin $n"

$mks -n "$n" -d "$d" $h 

# FAQ URL
h=$site/faq.html
n="FAQ"
d="Cygwin Frequently Asked Questions (with answers)"

$mks -n "$n" -d "$d" $h 


[-- Attachment #4: Type: text/plain, Size: 219 bytes --]


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Andrey Repin]

Greetings, Brian Inglis!

> On 2017-04-19 15:47, Jon Turney wrote:
>> On 19/04/2017 16:42, Brian Inglis wrote:
>>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>>> On Apr 16 12:22, Brian Inglis wrote:
>>>>> Could you please consider having setup-x86{,_64} install Windows
>>>>> shortcuts to at least the UG .pdf and index.html if present, in
>>>>> the .../Start Menu/Programs/Cygwin folder?
>>>>> A Windows URL shortcut to https://cygwin.com would also be helpful
>>>>> for some.
>>>> That requires to change setup or to provide a postinstall script.
>>>> Are you willing to provide the latter?

> Darn - hoped you wouldn't ask - attached, and preremove (if not filtered).
> Both tested on W10 without, and with CYGWINFORALL=-A and elevated/admin rights.
> Comments or improvements you could suggest, or changes you need made?

I would replace tabulation before "||" in etc.preremove.cygwin-doc.sh


-- 
With best regards,
Andrey Repin
Friday, April 21, 2017 19:09:56

Sorry for my terrible english...


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Brian Inglis]

On 2017-04-21 10:10, Andrey Repin wrote:
> Greetings, Brian Inglis!
>> On 2017-04-19 15:47, Jon Turney wrote:
>>> On 19/04/2017 16:42, Brian Inglis wrote:
>>>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>>>> On Apr 16 12:22, Brian Inglis wrote:
>>>>>> Could you please consider having setup-x86{,_64} install
>>>>>> Windows shortcuts to at least the UG .pdf and index.html if
>>>>>> present, in the .../Start Menu/Programs/Cygwin folder?
>>>>>> A Windows URL shortcut to https://cygwin.com would also be
>>>>>> helpful for some.
>>>>> That requires to change setup or to provide a postinstall
>>>>> script.
>>>>> Are you willing to provide the latter?
>> Darn - hoped you wouldn't ask - attached, and preremove (if not
>> filtered).
>> Both tested on W10 without, and with CYGWINFORALL=-A and
>> elevated/admin rights.
>> Comments or improvements you could suggest, or changes you need
>> made?
> I would replace tabulation before "||" in
> etc.preremove.cygwin-doc.sh

Well spotted - nit-picker ;^> - remnant from the systematic 
refactoring of a copy of postinstall down to the two line 
preremove.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Andrey Repin]

Greetings, Brian Inglis!

> On 2017-04-21 10:10, Andrey Repin wrote:
>> Greetings, Brian Inglis!
>>> On 2017-04-19 15:47, Jon Turney wrote:
>>>> On 19/04/2017 16:42, Brian Inglis wrote:
>>>>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>>>>> On Apr 16 12:22, Brian Inglis wrote:
>>>>>>> Could you please consider having setup-x86{,_64} install
>>>>>>> Windows shortcuts to at least the UG .pdf and index.html if
>>>>>>> present, in the .../Start Menu/Programs/Cygwin folder?
>>>>>>> A Windows URL shortcut to https://cygwin.com would also be
>>>>>>> helpful for some.
>>>>>> That requires to change setup or to provide a postinstall
>>>>>> script.
>>>>>> Are you willing to provide the latter?
>>> Darn - hoped you wouldn't ask - attached, and preremove (if not
>>> filtered).
>>> Both tested on W10 without, and with CYGWINFORALL=-A and
>>> elevated/admin rights.
>>> Comments or improvements you could suggest, or changes you need
>>> made?
>> I would replace tabulation before "||" in
>> etc.preremove.cygwin-doc.sh

> Well spotted - nit-picker ;^> - remnant from the systematic 
> refactoring of a copy of postinstall down to the two line 
> preremove.

Just happened to have visual whitespaces on when looking at your script
:)


-- 
With best regards,
Andrey Repin
Saturday, April 22, 2017 18:48:06

Sorry for my terrible english...


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Andrey Repin]

Greetings, Brian Inglis!

> On 2017-04-19 15:47, Jon Turney wrote:
>> On 19/04/2017 16:42, Brian Inglis wrote:
>>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>>> On Apr 16 12:22, Brian Inglis wrote:
>>>>> Could you please consider having setup-x86{,_64} install Windows
>>>>> shortcuts to at least the UG .pdf and index.html if present, in
>>>>> the .../Start Menu/Programs/Cygwin folder?
>>>>> A Windows URL shortcut to https://cygwin.com would also be helpful
>>>>> for some.
>>>> That requires to change setup or to provide a postinstall script.
>>>> Are you willing to provide the latter?

> Darn - hoped you wouldn't ask - attached, and preremove (if not filtered).
> Both tested on W10 without, and with CYGWINFORALL=-A and elevated/admin rights.
> Comments or improvements you could suggest, or changes you need made?

I would replace tabulation before "||" in etc.preremove.cygwin-doc.sh


-- 
With best regards,
Andrey Repin
Friday, April 21, 2017 19:09:56

Sorry for my terrible english...


--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Corinna Vinschen]

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

Hi Brian,

On Apr 20 21:00, Brian Inglis wrote:
> On 2017-04-19 15:47, Jon Turney wrote:
> > On 19/04/2017 16:42, Brian Inglis wrote:
> >> On 2017-04-19 04:58, Corinna Vinschen wrote:
> >>> On Apr 16 12:22, Brian Inglis wrote:
> >>>> Could you please consider having setup-x86{,_64} install Windows
> >>>> shortcuts to at least the UG .pdf and index.html if present, in
> >>>> the .../Start Menu/Programs/Cygwin folder?
> >>>> A Windows URL shortcut to https://cygwin.com would also be helpful
> >>>> for some.
> >>> That requires to change setup or to provide a postinstall script.
> >>> Are you willing to provide the latter?
> 
> Darn - hoped you wouldn't ask - attached, and preremove (if not filtered).
> Both tested on W10 without, and with CYGWINFORALL=-A and elevated/admin rights.
> Comments or improvements you could suggest, or changes you need made?

Only whitespace which I fixed locally.

But this is going to become part of the Cygwin repo (the cygwin-docs
package is created from there), so I need a BSD copyright waiver from
you.  See https://cygwin.com/contrib.html and the CONTRIBUTORS file in
the Cygwin repo:
https://cygwin.com/git/?p=newlib-cygwin.git;f=winsup/CONTRIBUTORS;hb=HEAD


Thanks,
Corinna

-- 
Corinna Vinschen                  Please, send mails regarding Cygwin to
Cygwin Maintainer                 cygwin AT cygwin DOT com
Red Hat

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: cygwin-doc html/ missing docbook.css and index dups cygwin-{api,ug-net}

[Brian Inglis]

On 2017-04-22 02:59, Corinna Vinschen wrote:
> On Apr 20 21:00, Brian Inglis wrote:
>> On 2017-04-19 15:47, Jon Turney wrote:
>>> On 19/04/2017 16:42, Brian Inglis wrote:
>>>> On 2017-04-19 04:58, Corinna Vinschen wrote:
>>>>> On Apr 16 12:22, Brian Inglis wrote:
>>>>>> Could you please consider having setup-x86{,_64} install Windows
>>>>>> shortcuts to at least the UG .pdf and index.html if present, in
>>>>>> the .../Start Menu/Programs/Cygwin folder?
>>>>>> A Windows URL shortcut to https://cygwin.com would also be helpful
>>>>>> for some.
>>>>> That requires to change setup or to provide a postinstall script.
>>>>> Are you willing to provide the latter?
>> Darn - hoped you wouldn't ask - attached, and preremove (if not filtered).
>> Both tested on W10 without, and with CYGWINFORALL=-A and elevated/admin rights.
>> Comments or improvements you could suggest, or changes you need made?
> Only whitespace which I fixed locally.
> But this is going to become part of the Cygwin repo (the cygwin-docs
> package is created from there), so I need a BSD copyright waiver from
> you.  See https://cygwin.com/contrib.html and the CONTRIBUTORS file in
> the Cygwin repo:
> https://cygwin.com/git/?p=newlib-cygwin.git;f=winsup/CONTRIBUTORS;hb=HEAD

Signed and sent to cygwin-patches as requested and documented.

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

--
Problem reports:       http://cygwin.com/problems.html
FAQ:                   http://cygwin.com/faq/
Documentation:         http://cygwin.com/docs.html
Unsubscribe info:      http://cygwin.com/ml/#unsubscribe-simple