[Spice-commits] 5 commits - docs/manual docs/spice_for_newbies.txt docs/spice_protocol.txt .gitlab-ci.yml

GitLab Mirror gitlab-mirror at kemper.freedesktop.org
Mon Dec 16 09:00:28 UTC 2019 

 .gitlab-ci.yml             |    6 ++++--
 docs/manual/manual.txt     |    8 ++++----
 docs/spice_for_newbies.txt |   19 +++++++------------
 docs/spice_protocol.txt    |   40 +++++++++++++++-------------------------
 4 files changed, 30 insertions(+), 43 deletions(-)

New commits:
commit ecd9a84837972e498e480af356428f2b00ff8150
Author: Snir Sheriber <ssheribe at redhat.com>
Date:   Sun Dec 15 14:48:05 2019 +0200

    ci: test docs with asciidocter before trigger spice-space ci
    
    Acked-by: Frediano Ziglio <fziglio at redhat.com>

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index edb3f408..fd110c78 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -167,9 +167,9 @@ websocket-autobahn:
   - server/tests/autobahn-check-report reports/servers/index.json
 
 trigger-website-update:
-  image: alpine:latest
+  image: ruby:latest
   before_script:
-  - apk add curl
+  - gem install asciidoctor
   only:
     variables:
     - $TOKEN
@@ -179,4 +179,6 @@ trigger-website-update:
     - "docs/manual/*.txt"
     - "docs/manual/images/*"
   script:
+  - asciidoctor -d book docs/*.txt docs/manual/*.txt > errors 2>&1
+  - if [ -n "$(cat errors)" ] ; then cat errors; exit 1 ; fi
   - curl -X POST -F token=$TOKEN -F ref=master https://gitlab.freedesktop.org/api/v4/projects/spice%2Fspice-space/trigger/pipeline
commit ebb7948b96f99ab6708fec370dc6109afdc71362
Author: Snir Sheriber <ssheribe at redhat.com>
Date:   Sun Dec 15 14:47:46 2019 +0200

    docs: update footnotes format in spice_for_newbies.txt
    
    Acked-by: Frediano Ziglio <fziglio at redhat.com>

diff --git a/docs/spice_for_newbies.txt b/docs/spice_for_newbies.txt
index 0ed2076f..f5a07d2d 100644
--- a/docs/spice_for_newbies.txt
+++ b/docs/spice_for_newbies.txt
@@ -31,7 +31,7 @@ image::g_cmd_flow.png[align="center"]
 +
 The above figure shows the basic Spice architecture and guest-to-client data
 flow of graphic commands, when using libspice with QEMU. libspice can be used by
-any other VDI footnoteref:[svdi,Spice VD Interfaces documentation] compatible
+any other VDIfootnote:svdi[Spice VD Interfaces documentation] compatible
 host application as well. Graphic commands data flow starts by a user
 application requesting the OS graphic engine (X or GDI) to perform a rendering
 operation. The graphic engine passes the commands to the QXL driver, which
@@ -145,7 +145,7 @@ factory for enabling RedClient to create channels by channel type.
 Spice server is implemented in libspice, a Virtual Device Interface (VDI) pluggable library. VDI
 provides a standard way to publish interfaces of virtual devices by a software component. This
 enables other software components to interact with these devices. For more information, refer to
-footnoteref:[svdi]. From one side, the server communicates with a remote client using the Spice
+footnote:svdi[]. From one side, the server communicates with a remote client using the Spice
 protocol. From the other side, it interacts with the VDI host application (e.g., QEMU).
 For display remoting purposes the server maintains a commands queue and a tree for managing the
 current objects dependencies and hidings. QXL commands are processed and translated to Spice
@@ -171,7 +171,7 @@ The main and input channels are controlled by handler functions (implemented in
 and cursor channels are handled by a red worker thread per display.  The audio playback and record
 channels have their own handlers (snd_worker.c). Libspice and the VDI host application (e.g. QEMU)
 communicate via interfaces defined for each functionality (e.g., QXL, agent, keyboard, mouse,
-tablet, playback, record), as detailed in footnoteref:[svdi].
+tablet, playback, record), as detailed in footnote:svdi[].
 +
 As shown in the above figures, spice server consists of the following major components:
 +
@@ -244,7 +244,7 @@ renderer addition.
 Spice protocol is used for client-server communication, i.e., for transferring graphical objects,
 keyboard and mouse events, cursor information, audio playback and record chunks, and control
 commands. Detailed documentation of the Spice protocol can be found in
-footnoteref:[spice_remote,Spice remote computing protocol definition].
+footnote:spice_remote[Spice remote computing protocol definition].
 +
 . QXL Device
 +
@@ -323,10 +323,10 @@ The server also uses OpenGL for hardware acceleration, sharing the same code as
 +
 Spice offers several image compression algorithms, which can be chosen on server initiation, and
 dynamically at run-time. Quic is Spice proprietary image compression utility which is based on the
-SFALIC algorithm footnoteref:[sfalic,Starosolski, R.:
+SFALIC algorithm footnote:sfalic[Starosolski, R.:
 http://sun.aei.polsl.pl/~rstaros/papers/s2006-spe-sfalic.pdf[Simple Fast and Adaptive Lossless Image
 Compression Algorithm], Software-Practice and Experience, 2007, 37(1):65-91, DOI 10.1002/spe.746.].
-The LZ (LZSS) footnoteref:[lzss,Lempel-Ziv-Storer-Szymanski: “Data compression via textual
+The LZ (LZSS) footnote:lzss[Lempel-Ziv-Storer-Szymanski: “Data compression via textual
 substitution” published in Journal of the ACM (pp. 928-951)] algorithm, adjusted to images, is
 another option. Both Quic and LZ are local algorithms, i.e., they encode each image independently.
 Global LZ (GLZ) is another Spice proprietary, that uses LZ with an history-based global dictionary.
@@ -394,7 +394,7 @@ client machine settings. This is implemented by a client command to the guest ag
 . 2-way Audio and Lip-sync
 +
 Spice supports audio playback and recording. Playback is compressed using the CELT
-footnoteref:[celt,http://www.celt-codec.org/[The CELT ultra-low delay audio codec]] algorithm.
+footnote:celt[http://www.celt-codec.org/[The CELT ultra-low delay audio codec]] algorithm.
 Lip-sync between video and audio is achieved by time-stamping the video frames in the QXL device and
 injecting them in the client side, synchronized with the audio, which is independent.
 +
commit 4761973bc885b348b13134643c496cb6a3bb1711
Author: Snir Sheriber <ssheribe at redhat.com>
Date:   Mon Dec 16 09:41:47 2019 +0200

    docs: fix manual.txt asciidoctor complaints
    
    Acked-by: Frediano Ziglio <fziglio at redhat.com>

diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt
index e95a563e..e282919b 100644
--- a/docs/manual/manual.txt
+++ b/docs/manual/manual.txt
@@ -560,7 +560,7 @@ the host.  This device must be added to the virtual machine as described below
 for the streaming agent to work in the guest.
 
 Guest Video Encoding: Agent Configuration
--------------------------------------------
+-----------------------------------------
 
 .Using virt-manager
 
@@ -808,7 +808,7 @@ up to libvirt:
 
 ****
 TODO proof-read the following section:
-*****
+****
 
 [source,sh]
 host$ virsh domdisplay
@@ -1159,7 +1159,7 @@ required Spice components.
 Client requirements
 ~~~~~~~~~~~~~~~~~~~
 
-See the https://gitlab.freedesktop.org/spice/spice-gtk/raw/master/README
+See the https://gitlab.freedesktop.org/spice/spice-gtk/raw/master/README.md
 [README file in spice-gtk] for the list of dependencies.
 
 Host requirements
@@ -1354,7 +1354,7 @@ Yaniv Kamay
 
 [[glossary]]
 Glossary
-========
+--------
 
 [glossary]
 Host::
commit e63896acf7136922b1f22ab448000257742b87b1
Author: Snir Sheriber <ssheribe at redhat.com>
Date:   Sun Dec 15 14:47:01 2019 +0200

    docs: make spice_for_newbies.txt comply with asciidoctor syntax check
    
    remove unused image reference
    
    Signed-off-by: Snir Sheriber <ssheribe at redhat.com>
    Acked-by: Frediano Ziglio <fziglio at redhat.com>

diff --git a/docs/spice_for_newbies.txt b/docs/spice_for_newbies.txt
index 091ae015..0ed2076f 100644
--- a/docs/spice_for_newbies.txt
+++ b/docs/spice_for_newbies.txt
@@ -26,7 +26,6 @@ client. Spice-related components include the QXL device and guest QXL driver.
 
 . Graphic Commands Flow
 +
-[#img-sunset]
 .Graphic Commands Flow
 image::g_cmd_flow.png[align="center"]
 +
@@ -53,7 +52,6 @@ display.
 +
 . Agent Commands Flow
 +
-[#img-sunset]
 .Agent Commands Flow
 image::a_cmd_flow.png[align="center"]
 +
@@ -76,7 +74,6 @@ Spice cross-platform (Linux & Windows) client is the interface for the end user.
 
 . Client Basic Structure
 +
-[#img-sunset]
 .Client Basic Structure
 image::cli_bsc_stc.png[align="center"]
 +
@@ -162,7 +159,6 @@ frame buffer are (1) Running out of resources; (2) The guest needs to read from
 +
 .. Server Structure
 +
-[#img-sunset]
 .Sever Structure
 image::srv_stc.png[align="center"]
 +
@@ -199,7 +195,6 @@ Reds is responsible for:
 +
 ... Graphics subsystem
 +
-[#img-sunset]
 .Graphics subsystem
 image::g_sub.png[align="center"]
 +
commit afa5e52f77638e41db879ca8a34b54363718ada2
Author: Snir Sheriber <ssheribe at redhat.com>
Date:   Sun Dec 8 14:16:45 2019 +0200

    docs: make spice_protocol.txt comply with asciidoctor syntax check
    
    Source code cannot be added in the middle of a table as is, place inside
    the a cell.
    
    https://asciidoctor.org/docs/user-manual/#pipe-in-table-cell
    
    Signed-off-by: Snir Sheriber <ssheribe at redhat.com>
    Acked-by: Frediano Ziglio <fziglio at redhat.com>

diff --git a/docs/spice_protocol.txt b/docs/spice_protocol.txt
index a6f0b01c..27e2d655 100644
--- a/docs/spice_protocol.txt
+++ b/docs/spice_protocol.txt
@@ -193,15 +193,11 @@ and ensure it was received within the allowed time-frame.
 +
 .. SpiceLinkMess definition.
 +
-[source,c]
-----
-UINT32 magic
-----
-+
-value of this fields must be equal to SPICE_MAGIC
-+
 [cols="2*"]
 |===
+|UINT32 magic
+|value of this fields must be equal to SPICE_MAGIC
+
 |UINT32 major_version
 | value of this fields must be equal to SPICE_VERSION_MAJOR
 
@@ -1413,20 +1409,16 @@ Pixmap lines are ordered from top to bottom (i.e., line 0 is the highest line).
 |UINT32 stride
 |number of bytes to add for moving from the beginning of line n to the
 beginning  of line n+1
-|===
-+
+
+a|
 [source,c]
 ----
 union {
-	SPICE_ADDRESS palette; /* address of the color palette. Must be zero if no
-color table is required for format */
+	SPICE_ADDRESS palette;
+	UINT64 palette_id;
 }
 ----
-+
-[cols="2*"]
-|===
-|UINT64 palette_id
-|id of the palette, valid if FLAG_PAL_FROM_CACHE is set
+|address of the color palette (must be zero if no color table is required for format) *or* id of the palette (valid if FLAG_PAL_FROM_CACHE is set).
 
 |SPICE_ADDRESS data
 |address of line 0 of the pixmap.
@@ -1471,20 +1463,18 @@ pixmap lines are ordered from top to bottom (i.e. line 0 is the highest line).
 
 |UINT32 data_size
 |size of compressed data
-|===
-+
+
+a|
 [source,c]
 ----
 union {
-	SPICE_ADDRESS palette; /* address of the color palette (see SpicePalette section
-in “Raw raster image”). Zero value is disallowed. */
-	UINT64 palette_id; /* id of the palette, valid if FLAG_PAL_FROM_CACHE
-is set. */
+	SPICE_ADDRESS palette;
+	UINT64 palette_id;
 }
 ----
-+
-[cols="2*"]
-|===
+|address of the color palette (see SpicePalette section in “Raw raster image”)[zero value
+is disallowed] *or* id of the palette (valid if FLAG_PAL_FROM_CACHE).
+
 |UINT8[] data
 |compressed pixmap
 |===

More information about the Spice-commits mailing list