Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Graphic or logo in the header #44

Open
wants to merge 28 commits into
base: develop
Choose a base branch
from
Open

Graphic or logo in the header #44

Changes from 3 commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
7ed9c20
Section about how to place a graphic or logo in the header of an docu…
der-schmelle2 Jul 1, 2018
e911f56
Add myself as author
der-schmelle2 Jul 1, 2018
3877f83
Add a link within the section
der-schmelle2 Jul 1, 2018
9dad7d6
Made alterations suggested through the review by @tomschr - Part I
der-schmelle2 Jul 10, 2018
f89141f
Imagefile handling within programlisting
der-schmelle2 Jul 10, 2018
f9c4c33
Build example stylesheet file
der-schmelle2 Jul 11, 2018
ffcf757
Merge branch develop into feature/pageheader-graphic
der-schmelle2 Jul 11, 2018
c324c08
Merge branch feature/pageheader-graphic into develop
der-schmelle2 Jul 11, 2018
6f34d84
Document redesign to prozedural steps
der-schmelle2 Jul 12, 2018
4b4d7c8
Syntax error in programlisting
der-schmelle2 Jul 13, 2018
283b9bc
Syntax error corrected, second time
der-schmelle2 Jul 13, 2018
339280c
Clarify the global option 'img.src.path'
der-schmelle2 Jul 13, 2018
17aa61d
Conducted the proposed changes by @tomschr
der-schmelle2 Jul 13, 2018
547da13
Conducted the proposed changes II
der-schmelle2 Jul 13, 2018
c6a9877
Discussion section rewritten
der-schmelle2 Jul 14, 2018
0e48460
Fixed two typos
der-schmelle2 Jul 15, 2018
bad3751
Conducted the proposed changes III
der-schmelle2 Jul 15, 2018
a5f09fd
Removed 'procedure' in line 192
der-schmelle2 Jul 16, 2018
4ad0914
oXygenXML line wrap a char 78
der-schmelle2 Jul 16, 2018
5afd918
oXygenXML view changes for 4K display
der-schmelle2 Jul 16, 2018
b554bf2
Merge branch 'develop' of https://github.com/tomschr/dbcookbook.git
der-schmelle2 Jul 24, 2018
73982f8
Merge remote-tracking branch 'origin/develop' into feature/pageheader…
der-schmelle2 Jul 25, 2018
7750465
Cleanup
der-schmelle2 Jul 25, 2018
39ac4fe
test
der-schmelle2 Sep 23, 2018
56f952d
Rewritten with new header.table content
der-schmelle2 Sep 23, 2018
ac67984
<tag/> correction
der-schmelle2 Oct 4, 2018
8667d2d
Project File changed
der-schmelle2 Oct 31, 2018
6e644b9
Intended shortend in file
der-schmelle2 Nov 1, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 170 additions & 0 deletions en/xml/fo/topic.graphic-pageheader.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,170 @@
<?xml version="1.0" encoding="UTF-8"?>

<!--
License CC BY-NC-SA 3.0

This work is licensed under the
"Namensnennung – Keine kommerzielle Nutzung – Weitergabe unter
gleichen Bedingungen 3.0 Deutschland (CC BY-NC-SA 3.0)"
http://creativecommons.org/licenses/by-nc-sa/3.0/de/deed.de

Read the English translation here:

"Attribution-NonCommercial-ShareAlike 3.0 Unported (CC BY-NC-SA 3.0)"
http://creativecommons.org/licenses/by-nc-sa/3.0/

-->
<?xml-model href="file:../5.1/dbref.rnc" type="application/relax-ng-compact-syntax"?>
<section xml:id="dbc.fo.graphic-pageheader" remap="topic" userlevel="easy"
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink">
<title>Inserting Graphics to your Page Headers or Footers</title>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe rephrase it to "Inserting Graphics into Page Headers and Footer"?
Hmn, thinking about if "Logos" instead of "Graphics" would be more appropriate?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.
New title is: "Inserting Logos into Page Headers and Footers"

<info>
<author>
<personname>
<firstname>Peter</firstname>
<surname>Schmelzer</surname>
</personname>
</author>
<keywordset>
<keyword>page header</keyword>
<keyword>block</keyword>
<keyword>format</keyword>
<keyword>page</keyword>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add additional keywords like "header" and "footer". I would remove block, it's quite general and as such almost useless.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done.
Changed keywords to:

page header
page footer
header
footer
format
page

</keywordset>
<subjectset>
<subject>
<subjectterm>graphic</subjectterm>
</subject>
</subjectset>
</info>

<section role="problem">
<title>Problem</title>
<para>You need to know how to insert a graphic in your page header or footer.</para>
</section>

<section role="solution">
<title>Solution</title>
<para>First of all, you need to create a customization layer in your
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Basically, this is all nice and correct. However, not everybody read the book from start to end. Usually, users see a topic, jump in and read. That's why you cannot expect they know all the terms and workflows (for example, "customization layer").

I would suggest to structure the solution section like this:

  1. Explain first, why you need logos/graphics in the header or footer. What's the benefits?
  2. Present the user a very general idea what you will show. In your case, mention that the following stylesheet will create a logo on the right side only.
  3. Optionally, you can show the result as a nice graphic. That way, the reader has at least an idea what it is all about.

After you did your "introduction", give the reader a procedure with a step-by-step instruction how to create this solution. You can use Creating Permalinks as a blueprint or the XML file en/xml/html/topic.permalinks.xml.

Appyling that style to this topic would mean:

  1. Give your changes a file name, for example, logo-right-header.xsl. Basically, it can be any name as long as it is easy to remember and reflects its purpose.
  2. Make sure, your stylesheet is syntactically correct and starts with the appropriate root element (xsl:stylesheet).
  3. Apply steps 1-2 from the "Creating Permalinks" topic to your file.
  4. Finish your last step with the phrase: "Use your customization layer to transform your DocBook document into FO."

I guess, it would only need 3 to 4 steps.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

customization stylesheet containing the following code:</para>
<programlisting>&lt;!-- Path and name of your graphic file-->
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two issues:

  • add the attribute language="xml" into <programlisting>.
  • Add the missing XSLT header (root element, namespaces etc.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Further ideas which makes handling of such files easier:

  • Use <example> around your programlisting element.
    This makes it easier to refer to it and you can give it a title and name (see Creating Permalinks, Example 5.1
  • Outsource your XSLT stylesheet into a separate file and xi:include it in your XML source.
    This helps in making example files and (more important!) gives our readers the chance to download this file
  • Reduces the size of your XML file.

If you like this approach, I'd recommend the following:

  1. Create a directory logo under fo.
  2. Save you XSLT stylesheet in fo/logo/YOUR_STYLESHEET.xsl. Replace the placeholder YOUR_STYLESHEET.xsl with some useful name.
  3. Replace the content of your stylesheet code in your XML file with the following content:
<example xml:id="ex.fo.XXXXX">
   <title>Some good title (<filename>YOUR_STYLESHEET.xsl</filename>)</title>
   <info>
        <output xmlns="urn:x-toms:docbook-ext">
          <filename>logo/YOUR_STYLESHEET.xsl</filename>
        </output>
   </info>
   <programlistingco>
      <areaspec>
            <!-- Add your callouts through <area/> -->
      </areaspec>
      <programlisting language="xml" linenumbering="numbered"
          ><xi:include href="logo/YOUR_STYLESHEET.xsl" parse="text"
          /></programlisting>
   </programlistingco>
</example>

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, but with a similar way. I've placed all necessary files below the folder "graphic-pageheader/".

&lt;xsl:param name="header.image.filename">{$img.src.path}your-graphic.svg&lt;/xsl:param>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That won't work because you've included it as text. Text won't be replaced, you need the select attribute:

<xsl:param name="header.image.filename" select="concat($img.src.path, 'your-graphic.svg')"/>

Another idea from an implementation perspective: would it better to separate the logo file name from any path? In other words, the parameter header.image.filename could just hold the base file name (without any paths). The exact location is created in line 88 with the above concat(...) expression. What do you think?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what you mean. Do you mean this:
<xsl:param name="header.image.filename">your-graphic.svg>/xsl:param>
<xsl:param name="header.image.filename" select="concat($img.src.path, 'your-graphic.svg')"/>

Copy link
Owner

@tomschr tomschr Jul 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My idea was that header.image.filename contains only the file name and nothing else:

<xsl:param name="header.image.filename">your-graphic.svg</xsl:param>

The complete path would be built at the position where it is needed by concatenating it with $img.src.path. Does that make any sense? 😉

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. That makes sense. Thanks!
The complete solution looks like this?
<xsl:param name="img.src.path">./Images/</xsl:param>
<xsl:param name="header.image.filename">your-graphic.svg</xsl:param>
xsl:param name="header.image.filename" select="concat($img.src.path, 'your-graphic.svg')"/>
I‘m not sure if this is correct, because 'your-graphic.svg' after concatenation is incorrect.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost. 😉 These lines are correct:

<xsl:param name="img.src.path">./Images/</xsl:param>
<xsl:param name="header.image.filename">your-graphic.svg</xsl:param>

A little bit deeper you use the parameter header.image.filename in this code:

&lt;xsl:call-template name="fo-external-image"><co xml:id="co.topic.graphic-pageheader.template"/>
     &lt;xsl:with-param name="filename" select="concat($img.src.path, $header.image.filename)"/><co xml:id="co.topic.graphic-pageheader.file"/>>
&lt;/xsl:call-template>

Keep in mind the following changes in comparison to your code:

  • xsl:param inside xsl:call-template has to be xsl:with-param.
  • the parameter for the template fo-external-image has to be filename, not header.image.filename.
  • you pass the complete path in the select attribute of xsl:with-param.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

&lt;!-- Header rule yes (1) / no (0) -->
&lt;xsl:param name="header.rule" select="0"/>

&lt;xsl:template name="header.content"><co xml:id="co.topic.graphic-pageheader.content"/>
&lt;xsl:param name="pageclass" select="''"<co xml:id="co.topic.graphic-pageheader.variables"/>
&lt;xsl:param name="sequence" select="''"/>
&lt;xsl:param name="position" select="''"/>
&lt;xsl:param name="gentext-key" select="''"/>
&lt;fo:block><co xml:id="co.topic.graphic-pageheader.block"/>
&lt;!-- sequence can be odd, even, first, blank -->
&lt;!-- position can be left, center, right -->
&lt;xsl:choose>
&lt;xsl:when test="$sequence = 'blank'">
&lt;!-- nothing --><co xml:id="co.topic.graphic-pageheader.blank"/>
&lt;/xsl:when>

&lt;xsl:when test="$position='left'">
&lt;!-- Same for odd, even, empty, and blank sequences -->
&lt;!-- nothing -->
&lt;/xsl:when>

&lt;xsl:when test="($sequence='odd' or $sequence='even') and $position='center'">
&lt;!-- nothing -->
&lt;/xsl:when>

&lt;xsl:when test="$position='center'"><co xml:id="co.topic.graphic-pageheader.center"/>
&lt;!-- nothing for empty and blank sequences -->
&lt;/xsl:when>

&lt;xsl:when test="$position='right'"><co xml:id="co.topic.graphic-pageheader.right"/>
&lt;!-- Same for odd, even, empty, and blank sequences -->
&lt;fo:external-graphic content-height="25mm"><co xml:id="co.topic.graphic-pageheader.height"/>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmn... hard-coded values are not always as constant as we wish. 😉 I would suggest to outsource it into a parameter. This gives the user the chance to change it as needed.

&lt;xsl:attribute name="src"><co xml:id="co.topic.graphic-pageheader.attribute"/>
&lt;xsl:call-template name="fo-external-image"><co xml:id="co.topic.graphic-pageheader.template"/>
&lt;xsl:with-param name="filename" select="$header.image.filename"/>
<co xml:id="co.topic.graphic-pageheader.file"/>>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the line break and add the <co/> right after the end of line 88.

&lt;/xsl:call-template>
&lt;/xsl:attribute>
&lt;/fo:external-graphic>
&lt;/xsl:when>

&lt;xsl:when test="$sequence = 'first'">
&lt;!-- nothing for first pages -->
&lt;/xsl:when>

&lt;xsl:when test="$sequence = 'blank'">
&lt;!-- nothing for blank pages -->
&lt;/xsl:when>
&lt;/xsl:choose>
&lt;/fo:block>
&lt;/xsl:template></programlisting>
<calloutlist>
<callout arearefs="co.topic.graphic-pageheader.content">
<para>We assume that your graphic should be placed in the header
of all pages except title pages.</para>
</callout>
<callout arearefs="co.topic.graphic-pageheader.variables">
<para>The content of the necessary variables needs to be cleared.</para>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, it's the default value. This value is used, when the caller doesn't define the parameter.

</callout>
<callout arearefs="co.topic.graphic-pageheader.block">
<para>A <tag>block</tag>-element creates a rectangle area on a page
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • block -> fo:block

which can contain <tag>lists</tag>, <tag>tables</tag> or <tag>graphics</tag>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Avoid these tag elements for list, tables, and graphics. They are not specific elements, but concepts.

.</para>
</callout>
<callout arearefs="co.topic.graphic-pageheader.blank">
<para>Here you can place an banner like '<emphasis>This page is
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • place an banner -> place a banner; or even better use "insert text like..."
  • Remove the apostroph before <emphasis>

intentionally left blank'</emphasis> or so.</para>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove the "or so".

</callout>
<callout arearefs="co.topic.graphic-pageheader.center">
<para>This is a good place for the chapter title.</para>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do you do that? That can be a good place for the discussion.

</callout>
<callout arearefs="co.topic.graphic-pageheader.right">
<para>This is the place where we want to place our graphic. The
graphic should be visible on all pages on the right side.</para>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This statement should be added before you present your stylesheet.

</callout>
<callout arearefs="co.topic.graphic-pageheader.height">
<para>The graphic picture is too big, so we limit his height to 25mm.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe rephrase the sentence as:

To avoid pictures which are too big for the headline, we limit its height to 25mm.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

When you specify only one parameter like <tag>height</tag>or<tag>width</tag>,
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add spaces between "height", "or", and "width".

your graphic will be scaled with the <link
xlink:href="#li.fo.external-graphics">correct aspect ratio</link>.</para>
</callout>
<callout arearefs="co.topic.graphic-pageheader.attribute">
<para>We will give the graphic which will be used the attribute.
<emphasis>src</emphasis>.</para>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That isn't an English sentence. 😉 Maybe something like this:

The filename is passed on the <tag class="attribute">src</tag> attribute.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. :-)
Thanks!

</callout>
<callout arearefs="co.topic.graphic-pageheader.template">
<para>The template which is called to import and place the graphic.</para>
</callout>
<callout arearefs="co.topic.graphic-pageheader.file">
<para>Our file defined at the top of our customization layer.</para>
</callout>
</calloutlist>
</section>
<section role="discussion">
<title>Discussion</title>
<para>If you wish to place your graphic within the footer, replace
<tag>header.content</tag>with<tag>footer.content</tag>.</para>
</section>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The discussion is a bit... well, very short. 😉

Usually, I apply the following approach for each topic:

  • First, I state the problem
  • Second, I present a solution which is easy, general, or short.
  • Third, I present further additions. What can the reader do with that solution? Maybe he has further needs, wishes, or problems?

Overall, I try to make the solution more general, but the discussion more specific.

As a reader, I would expect some additional ideas. Some ideas that come to my mind and could be added:

  • Why do I need that? What are the reasons? At least, this is very important to give the reader a purpose.
    This could be layout issues, corporate identity, etc.
  • What should I do when I have a double sided document?
    Your solution does not take into account double sided documents, right?
  • What should I change, if I want my logo appear left on a verso page and right on a recto page?
  • Are there any recommendations prior to this stylesheets in regards to file size, file format etc.?
  • Could I change the logo depending on the chapter?
    For example, the logo file name could be added in the info element of the respective chapter

Of course, you don't have to describe all of them. It's just an idea what can be included.

<section role="seealso">
<title>See Also</title>
<itemizedlist>
<listitem xml:id="li.fo.external-graphics">
<para>Full parameter description for <tag>fo:external-graphic</tag><link
xlink:href="http://www.w3.org/TR/xsl/#fo_external-graphic"/></para>
</listitem>
<listitem>
<para>Parameter description for <tag>xsl:attribute</tag><link
xlink:href="https://www.w3schools.com/xml/ref_xsl_el_attribute.asp"/></para>
</listitem>
<listitem>
<para>Parameter description for <tag>xsl:with-param</tag> <link
xlink:href="https://www.w3schools.com/xml/ref_xsl_el_with-param.asp"/></para>
</listitem>
</itemizedlist>
</section>
</section>