[libvirt] [PATCH v2 0/2] Enum formating changes
v2 contains a tweak to the CSS to widen the page slightly and keep borders on narrow screen. Peter Krempa (2): docs: Format bit shift and hex notation for bitwise flag enums docs: css: Make docs page wider while still accomodating narrow screens docs/apibuild.py | 10 ++++++++++ docs/libvirt.css | 9 +++++++-- docs/newapi.xsl | 22 ++++++++++++++++++++-- 3 files changed, 37 insertions(+), 4 deletions(-) -- 2.20.1
Big number itself does not make much sense in some cases. Format the bitshift format as well. Changes our web page docs from: VIR_MIGRATE_POSTCOPY = 32768 : Setting the VIR_MIGRATE_POSTCOPY... VIR_MIGRATE_TLS = 65536 : Setting the VIR_MIGRATE_TLS flag... to: VIR_MIGRATE_POSTCOPY = 32768 (0x8000; 1 << 15) : Setting the VIR_MIGRATE_POSTCOPY... VIR_MIGRATE_TLS = 65536 (0x10000; 1 << 16) : Setting the VIR_MIGRATE_TLS flag... Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/apibuild.py | 10 ++++++++++ docs/libvirt.css | 4 ++++ docs/newapi.xsl | 22 ++++++++++++++++++++-- 3 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/apibuild.py b/docs/apibuild.py index 3ef5d0f554..9e04871220 100755 --- a/docs/apibuild.py +++ b/docs/apibuild.py @@ -2117,12 +2117,22 @@ class docBuilder: self.modulename_file(id.header))) if id.info is not None: info = id.info + valhex = "" if info[0] is not None and info[0] != '': try: val = eval(info[0]) + valhex = hex(val) except: val = info[0] output.write(" value='%s'" % (val)) + + if valhex != "": + output.write(" value_hex='%s'" % (valhex)) + + m = re.match("\(?1<<(\d+)\)?", info[0]) + if m: + output.write(" value_bitshift='%s'" % (m.group(1))) + if info[2] is not None and info[2] != '': output.write(" type='%s'" % info[2]) if info[1] is not None and info[1] != '': diff --git a/docs/libvirt.css b/docs/libvirt.css index e590b33cfb..c5fe27fa3f 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -537,3 +537,7 @@ dl.mail dt a:hover { color: rgb(255, 230, 0); text-decoration: none; } + +td.enumvalue { + white-space: nowrap; +} diff --git a/docs/newapi.xsl b/docs/newapi.xsl index 8d4c032c03..c808fe5ff8 100644 --- a/docs/newapi.xsl +++ b/docs/newapi.xsl @@ -288,6 +288,24 @@ </xsl:choose> </xsl:template> + <xsl:template name="enumvalue"> + <xsl:param name="value" select="@value"/> + <xsl:param name="valuehex" select="@value_hex"/> + <xsl:param name="valuebitshift" select="@value_bitshift"/> + <xsl:value-of select="@value"/> + <xsl:if test="$valuehex != '' or $valuebitshift != ''"> + <xsl:text> (</xsl:text> + <xsl:if test="$valuehex != ''"> + <xsl:value-of select="@value_hex"/> + </xsl:if> + <xsl:if test="$valuebitshift != ''"> + <xsl:text>; 1 << </xsl:text> + <xsl:value-of select="@value_bitshift"/> + </xsl:if> + <xsl:text>)</xsl:text> + </xsl:if> + </xsl:template> + <xsl:template match="typedef[@type = 'enum']"> <xsl:variable name="name" select="string(@name)"/> <h3><a name="{$name}"><code><xsl:value-of select="$name"/></code></a></h3> @@ -306,7 +324,7 @@ <td><xsl:text> = </xsl:text></td> <xsl:choose> <xsl:when test="@info != ''"> - <td><xsl:value-of select="@value"/></td> + <td class="enumvalue"><xsl:call-template name="enumvalue"/></td> <td> <div class="comment"> <xsl:call-template name="dumptext"> @@ -316,7 +334,7 @@ </td> </xsl:when> <xsl:otherwise> - <td colspan="2"><xsl:value-of select="@value"/></td> + <td colspan="2" class="enumvalue"><xsl:call-template name="enumvalue"/></td> </xsl:otherwise> </xsl:choose> </tr> -- 2.20.1
On Tue, Jan 29, 2019 at 04:32:35PM +0100, Peter Krempa wrote:
Big number itself does not make much sense in some cases. Format the bitshift format as well.
Changes our web page docs from:
VIR_MIGRATE_POSTCOPY = 32768 : Setting the VIR_MIGRATE_POSTCOPY... VIR_MIGRATE_TLS = 65536 : Setting the VIR_MIGRATE_TLS flag...
to:
VIR_MIGRATE_POSTCOPY = 32768 (0x8000; 1 << 15) : Setting the VIR_MIGRATE_POSTCOPY... VIR_MIGRATE_TLS = 65536 (0x10000; 1 << 16) : Setting the VIR_MIGRATE_TLS flag...
Neat! Formatting this also in roman numerals might be useful to some. Jano
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/apibuild.py | 10 ++++++++++ docs/libvirt.css | 4 ++++ docs/newapi.xsl | 22 ++++++++++++++++++++-- 3 files changed, 34 insertions(+), 2 deletions(-)
Bump the width to 85em while keeping a maximum width of 90%. Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/libvirt.css b/docs/libvirt.css index c5fe27fa3f..dcae2a338a 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -100,14 +100,15 @@ margin-right: auto; padding: 0px; padding-bottom: 1em; - max-width: 60em; + max-width: 90%; + width: 85em; } body.index #content, body.docs #content, body.hvsupport #content { - max-width: inherit; + width: inherit; } pre { -- 2.20.1
On Tue, Jan 29, 2019 at 04:32:36PM +0100, Peter Krempa wrote:
Bump the width to 85em while keeping a maximum width of 90%.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css index c5fe27fa3f..dcae2a338a 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -100,14 +100,15 @@ margin-right: auto; padding: 0px; padding-bottom: 1em; - max-width: 60em; + max-width: 90%; + width: 85em; }
FYI, the reason I originally chose 60em is because that is commonly considered to be the optimal length for readability https://baymard.com/blog/line-length-readability This is more important for large blocks of text, eg magazine articles blog posts, etc. Our APIs docs have alot more structured information, even though it does have some blocks of text as description it is not so critical to adhere to the normal guidelines. We also potentially have trouble where very long C identifiers might force unnatural line breaks in our API docs. Personally I do still find it easier to read the APIs docs with the narrower 60em width than 85em. Was there a particular reason you picked 85ems or was it arbitrary, and where there specific parts of the docs that had trouble with 60 ems ? I'm wondering if some figure inbetween might cope with the bad bits you saw, without making things quite so wide. eg would 70em be sufficient ?
body.index #content, body.docs #content, body.hvsupport #content { - max-width: inherit; + width: inherit; }
pre {
Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Wed, Jan 30, 2019 at 16:31:56 +0000, Daniel Berrange wrote:
On Tue, Jan 29, 2019 at 04:32:36PM +0100, Peter Krempa wrote:
Bump the width to 85em while keeping a maximum width of 90%.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css index c5fe27fa3f..dcae2a338a 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -100,14 +100,15 @@ margin-right: auto; padding: 0px; padding-bottom: 1em; - max-width: 60em; + max-width: 90%; + width: 85em; }
FYI, the reason I originally chose 60em is because that is commonly considered to be the optimal length for readability
https://baymard.com/blog/line-length-readability
This is more important for large blocks of text, eg magazine articles blog posts, etc. Our APIs docs have alot more structured information, even though it does have some blocks of text as description it is not so critical to adhere to the normal guidelines. We also potentially have trouble where very long C identifiers might force unnatural line breaks in our API docs.
Personally I do still find it easier to read the APIs docs with the narrower 60em width than 85em.
Was there a particular reason you picked 85ems or was it arbitrary, and where there specific parts of the docs that had trouble with 60 ems ? I'm wondering if some figure inbetween might cope with the bad bits you saw, without making things quite so wide. eg would 70em be sufficient ?
70em is okay for me. Basically the reason was that 60em does not even fill my portrait monitor with rather oldschool resolution and e.g. in cases of the enum description boxes the description gets too many linebreaks which are harder to follow if the line does not start at the left border. Said that, my screen is not much wider than the 60em we have normally but I'm not entirely a fan of excesive borders or no borders at all. That's the reason to change max-width to a percent measurement and set width. In this case I'd even change it to 95% which leaves enough border. In the end none of this is critical. I have lots of CSS overrides for many webpages so I can install one more :)
On Thu, Jan 31, 2019 at 09:44:56AM +0100, Peter Krempa wrote:
On Wed, Jan 30, 2019 at 16:31:56 +0000, Daniel Berrange wrote:
On Tue, Jan 29, 2019 at 04:32:36PM +0100, Peter Krempa wrote:
Bump the width to 85em while keeping a maximum width of 90%.
Signed-off-by: Peter Krempa <pkrempa@redhat.com> --- docs/libvirt.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/libvirt.css b/docs/libvirt.css index c5fe27fa3f..dcae2a338a 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -100,14 +100,15 @@ margin-right: auto; padding: 0px; padding-bottom: 1em; - max-width: 60em; + max-width: 90%; + width: 85em; }
FYI, the reason I originally chose 60em is because that is commonly considered to be the optimal length for readability
https://baymard.com/blog/line-length-readability
This is more important for large blocks of text, eg magazine articles blog posts, etc. Our APIs docs have alot more structured information, even though it does have some blocks of text as description it is not so critical to adhere to the normal guidelines. We also potentially have trouble where very long C identifiers might force unnatural line breaks in our API docs.
Personally I do still find it easier to read the APIs docs with the narrower 60em width than 85em.
Was there a particular reason you picked 85ems or was it arbitrary, and where there specific parts of the docs that had trouble with 60 ems ? I'm wondering if some figure inbetween might cope with the bad bits you saw, without making things quite so wide. eg would 70em be sufficient ?
70em is okay for me. Basically the reason was that 60em does not even fill my portrait monitor with rather oldschool resolution and e.g. in cases of the enum description boxes the description gets too many linebreaks which are harder to follow if the line does not start at the left border.
Said that, my screen is not much wider than the 60em we have normally but I'm not entirely a fan of excesive borders or no borders at all. That's the reason to change max-width to a percent measurement and set width. In this case I'd even change it to 95% which leaves enough border.
In the end none of this is critical. I have lots of CSS overrides for many webpages so I can install one more :)
Lets push with 70em then, as it is desirable to avoid enum descriptions getting wrapped too aggressively. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
On Tue, Jan 29, 2019 at 04:32:34PM +0100, Peter Krempa wrote:
v2 contains a tweak to the CSS to widen the page slightly and keep borders on narrow screen.
Peter Krempa (2): docs: Format bit shift and hex notation for bitwise flag enums docs: css: Make docs page wider while still accomodating narrow screens
docs/apibuild.py | 10 ++++++++++ docs/libvirt.css | 9 +++++++-- docs/newapi.xsl | 22 ++++++++++++++++++++-- 3 files changed, 37 insertions(+), 4 deletions(-)
Regardless of whether you go with my suggestion in 1/2: Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
participants (3)
-
Daniel P. Berrangé -
Ján Tomko -
Peter Krempa