Fix tarball builds

common.xml end up being in srcdir, unlike all the generated
xml files, making inclusion difficult. Just include the
contents directly.

doc/Makefile.am

@@ -71,7 +71,6 @@ EXTRA_DIST = \
 	org.freedesktop.portal.Flatpak.xml \
 	docbook.css		\
 	portal-docs.xml.in	\
-	common.xml		\
 	xmlto-config.xsl	\
 	$(NULL)
 
@@ -94,7 +93,7 @@ doc_DATA = 			\
 	docbook.css		\
 	$(NULL)
 
-portal-docs.html: portal-docs.xml common.xml $(xml_files) xmlto-config.xsl
+portal-docs.html: portal-docs.xml $(xml_files) xmlto-config.xsl
 	$(AM_V_GEN) $(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks -m $(srcdir)/xmlto-config.xsl $<
 
 endif # DOCBOOK_DOCS_ENABLED

doc/portal-docs.xml.in

@@ -8,7 +8,48 @@
     <title>Portal Documentation</title>
     <releaseinfo>Version @VERSION@</releaseinfo>
   </bookinfo>
-  <xi:include href="common.xml"/>
+  <chapter id="common-conventions">
+    <title>Common Conventions</title>
+    <section>
+      <title>Portal requests</title>
+      <para>
+        Requests made via portal interfaces generally involve user interaction.
+      </para>
+      <para>
+        The general flow of the portal API is that the application makes
+        a portal request, the portal replies to that method call with a
+        handle (i.e. object path) to Request object that corresponds to the
+        request. The object is exported on the bus and stays alive as long
+        as the user interaction lasts. When the user interaction is over,
+        the portal sends a Response signal back to the application with
+        the results from the interaction, if any.
+      </para>
+    </section>
+    <section id="parent_window"> 
+      <title>Parent window identifiers</title>
+      <para>
+        Most portals interact with the user by showing dialogs. These dialogs
+        should generally be placed on top of the application window that triggered
+        them. To arrange this, the compositor needs to know about the application
+        window. Many portal requests expect a "parent_window" string argument for
+        this reason.
+      </para>
+      <para>
+        Under X11, the "parent_window" argument should have the form
+        "x11:<replaceable>XID</replaceable>", where <replaceable>XID</replaceable>
+        is the XID of the application window.
+      </para>
+      <para>
+        Under Wayland, it should have the form "wayland:<replaceable>HANDLE</replaceable>",
+        where <replaceable>HANDLE</replaceable> is a surface handle obtained with the
+        <ulink url="https://github.com/wayland-project/wayland-protocols/blob/master/unstable/xdg-foreign/xdg-foreign-unstable-v2.xml">xdg_foreign</ulink> protocol.
+      </para>
+      <para>
+        For other windowing systems, or if you don't have a suitable handle, just
+        pass an empty string for "parent_window".
+      </para>
+    </section>
+  </chapter>
   <reference>
     <title>Portal API Reference</title>
     <partintro>