[wayland-web] Adding notes regarding Arch Linux dependencies for DocBook.

Submitted by Jon Cruz on Dec. 8, 2014, 2:49 p.m.

Details

Message ID 1418050161-10514-1-git-send-email-jonc@osg.samsung.com
State Accepted
Headers show

Not browsing as part of any series.

Commit Message

Jon Cruz Dec. 8, 2014, 2:49 p.m.
Adding simple notes on DocBook dependencies needed when building on Arch Linux.
Without these being present the documentation build will attempt network access
and fail outright or warn and then not produce correct results when no Internet
access is present.

Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86515

Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
---
 building.html | 4 ++++
 1 file changed, 4 insertions(+)

Patch hide | download patch | download mbox

diff --git a/building.html b/building.html
index 401069b..fbedfae 100644
--- a/building.html
+++ b/building.html
@@ -42,6 +42,8 @@  Linux Mint 17</a>, which is derived from Ubuntu 14.04.</li>
 <li>For building Weston for <a href="http://www.raspberrypi.org/">Raspberry
 Pi</a>, see <a href="raspberrypi.html">Raspberry Pi build guide</a>.</li>
 
+<li>For building Wayland on Arch note that <a href="https://wiki.archlinux.org/index.php/Docbook#Setting_up_Docbook_in_Arch">DocBook dependencies</a> will be needed when building documentation.</li>
+
 </ul>
 
 <h2>Hardware / Drivers</h2>
@@ -119,6 +121,8 @@  $ cd ..
 <li>You can avoid the <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> dependency
 with <code>--disable-documentation</code>.</li>
 
+<li>Under Arch Linux,  <a href="https://wiki.archlinux.org/index.php/Docbook#Setting_up_Docbook_in_Arch">DocBook dependencies</a> will be needed when building documentation. These include <code>docbook-xml</code> and <code>docbook-xsl</code>.</li>
+
 </ul>
 
 <h2>Mesa</h2>

Comments

On 08/12/14 08:49 AM, Jon A. Cruz wrote:
> Adding simple notes on DocBook dependencies needed when building on Arch Linux.
> Without these being present the documentation build will attempt network access
> and fail outright or warn and then not produce correct results when no Internet
> access is present.

Any way we can print a more descriptive error at failure time instead of
just hiding a clue in the docs?  Or can we just disable docbook if deps
aren't present?

I'm not certain Arch will be the only distribution to ever have this
problem, and the comment could get a little unwieldy...

(Why is this reaching out over the internet anyway?  Is this a bug that
should be brought up with an Arch package maintainer?)

> Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86515
> 
> Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
> ---
>  building.html | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/building.html b/building.html
> index 401069b..fbedfae 100644
> --- a/building.html
> +++ b/building.html
> @@ -42,6 +42,8 @@ Linux Mint 17</a>, which is derived from Ubuntu 14.04.</li>
>  <li>For building Weston for <a href="http://www.raspberrypi.org/">Raspberry
>  Pi</a>, see <a href="raspberrypi.html">Raspberry Pi build guide</a>.</li>
>  
> +<li>For building Wayland on Arch note that <a href="https://wiki.archlinux.org/index.php/Docbook#Setting_up_Docbook_in_Arch">DocBook dependencies</a> will be needed when building documentation.</li>
> +
>  </ul>
>  
>  <h2>Hardware / Drivers</h2>
> @@ -119,6 +121,8 @@ $ cd ..
>  <li>You can avoid the <a href="http://www.stack.nl/~dimitri/doxygen/">Doxygen</a> dependency
>  with <code>--disable-documentation</code>.</li>
>  
> +<li>Under Arch Linux,  <a href="https://wiki.archlinux.org/index.php/Docbook#Setting_up_Docbook_in_Arch">DocBook dependencies</a> will be needed when building documentation. These include <code>docbook-xml</code> and <code>docbook-xsl</code>.</li>
> +
>  </ul>
>  
>  <h2>Mesa</h2>
>
On 12/09/2014 08:35 AM, Derek Foreman wrote:
> 
> Any way we can print a more descriptive error at failure time instead of
> just hiding a clue in the docs?  Or can we just disable docbook if deps
> aren't present?
> 
> I'm not certain Arch will be the only distribution to ever have this
> problem, and the comment could get a little unwieldy...
> 

I'd been thinking the same. However it turns out that a check is
non-trivial and most likely involves bringing in another GPL'd file or
two. In the meantime documenting the requirement can reduce the number
of times it trips people up.



> (Why is this reaching out over the internet anyway?  Is this a bug that
> should be brought up with an Arch package maintainer?)
> 


Some depends on what xmlto passes internally to the xslt processor. It
appears a switch for this was changed at some point.

Simple ways to block it are not immediately present in xmlto. However,
it is a case of it attempting to fetch primary stylesheets that were to
be used for main processing as opposed to merely fetching the DTDs for
files as they were processed (a different common problem).
On Mon,  8 Dec 2014 06:49:21 -0800
"Jon A. Cruz" <jonc@osg.samsung.com> wrote:

> Adding simple notes on DocBook dependencies needed when building on Arch Linux.
> Without these being present the documentation build will attempt network access
> and fail outright or warn and then not produce correct results when no Internet
> access is present.
> 
> Fixes: https://bugs.freedesktop.org/show_bug.cgi?id=86515
> 
> Signed-off-by: Jon A. Cruz <jonc@osg.samsung.com>
> ---
>  building.html | 4 ++++
>  1 file changed, 4 insertions(+)

I think this is better than nothing, so pushed.

Sounds like it cannot really be helped much, so I also marked the bug
as WORKSFORME.


Thanks,
pq