Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)

[chrispitude]

Hi everyone,

I've started this topic to discuss how one or more CSS files might be shared between customizing the authoring window and controlling Chemistry PDF output (and possibly WebHelp HTML5 output, but that's not my focus now).

My writers are FrameMaker veterans that are used to seeing the printed page when they author. I want to preserve that experience as much as possible. I created a single CSS file and (1) associated it with DITA topics via a Document Type Association extension, and (2) specified it with the args.css parameter of Oxygen PDF Chemistry.

I originally created my CSS file as a full (non-alternate) file by including "-dita.css" at the top of my file, followed by all my formatting settings:

Code: Select all

@import "${frameworks}/dita/css/core/-dita.css";

:root {
    line-height:1.0;
    font-family: "Arial", "Helvetica", sansserif;
    font-size: 11;
}
...etc...

When I did this, (1) the editing window reflected the settings, (2) the temporary HTML file from Chemistry reflected the settings, but (3) the final PDF did not. Something in the -dita.css file breaks that final HTML-to-PDF rendering and causes all formatting in the CSS file to be rejected. I fixed this by not including "-dita.css" in my file and making it an alternate style on top of the built-in "Pure" style.

I see that some settings are honored in one place but not another. For example, I use the following to add a prefix to DITA note elements in the editor:

Code: Select all

*[class ~= "topic/note"] { margin-left: 0.25in; }
*[class ~= "topic/note"]:before { margin-left: -0.25in; padding-left: 0in; }
*[class ~= "topic/note"][type]:before { content: "UNKNOWN NOTE TYPE:"; }
*[class ~= "topic/note"][type = "note"]:before { content: "Note:"; }
*[class ~= "topic/note"][type = "caution"]:before { content: "Caution:"; }
*[class ~= "topic/note"][type = "tip"]:before { content: "Tip:"; }

But then I found that Chemistry is adding its own note prefix via a span in the intermediate HTML:

Code: Select all

<div class="- topic/note note note note_note"><span class="note__title">Note:</span> 
      <p class="- topic/p p">blah blah blah.</p>
    </div>

which caused the PDF to have two note prefixes (the explicit span one and the CSS-applied one). I fixed that after finding a discussion topic with the solution.

I also see that additional margins, paddings, etc. are getting applied by the Chemistry defaults that will require more print-only overrides. I guess I will put these all in a @media print {} block so it's clear they're print-only, and so there's no chance of odd interactions with future editor customization.

For those of you who configured your authoring experience to match your PDF output, what CSS approach and structure did you find worked best for you? Did you run into any tricky problems that you'd like to share? (I can already see that synchronizing counters and figure/table/title cross-reference text between formats is going to be difficult!)

- Chris

[Costin]

Hello,

It is very complicated to guess what you tried to obtain and what did not work only by reading this post.
I'm pretty sure that the issues you encountered are related to specificity. More exactly, there could be some rules in the dita.css or other default CSS files used by oXygen, that have a higher specificity than the ones you are using in your customization .css file.

So you must make sure that you use more specific rules. One thing that could help you see which CSS files are applied over the output is your internet browser's CSS inspector tool.
Just open the merged.html (in case of PDF publishing) or the index.html (in case of WebHelp Responsive publishing) in the browser and inspect the style. After you identify the default CSS files that are applied over the output, you could then debug this further, using more specific rules to override the ones that come from those CSS files.

If you still can not manage to obtain the expected output, you could send us the customization CSS that you are using and let us know how would you expect the output to look like and what did not work so, as time would allow us, we could take a look and see if we could help you develop your CSS.

Regards,
Costin

[chrispitude]

Hi Costin,

First, thanks for the generous offer of help! I started the thread mostly because I am interested to hear how people approach CSS customization in broad terms. I don't want to volunteer you to fix all the individual issues I'm fighting.

My CSS style is an alternate (incremental) style of the "Pure" CSS style (frameworks/dita/css/edit/style-pure.css). Ideally, the baseline would have as little styling as possible, so that my own CSS file spent its effort defining styles rather than removing them.

However, edit/style-pure.css includes edit/dita.css, which includes core/-dita.css, which includes a whole bunch of things!

Code: Select all

$ egrep -c '(margin|padding|border|content|font|decoration)' ./*
./-bookmap-content.css:34
./-bookmap-metadata.css:3
./-bookmap.css:1
./-colors.css:13
./-concept.css:3
./-conrefs.css:49
./-d4p.css:12
./-dita.css:1
./-domain-delay-d.css:7
./-domain-hazard-d.css:26
./-domain-hi-d.css:15
./-domain-markup-d.css:1
./-domain-pr-d.css:35
./-domain-sw-d.css:17
./-domain-taskreq-d.css:25
./-domain-troubleshooting.css:17
./-domain-ui-d.css:7
./-domain-ut-d.css:48
./-domain-xml-mention-domain.css:15
./-domain-xnal.css:0
./-glossary-related.css:2
./-glossary.css:4
./-group-display-atts.css:25
./-i18n-de.css:137
./-i18n-en.css:136
./-i18n-fr.css:136
./-i18n.css:0
./-learning-common-content.css:28
./-learning-common-interraction.css:20
./-learning-spec-interraction-base.css:9
./-learning-spec-map.css:3
./-learning-spec-metadata.css:3
./-learning-spec-topics.css:8
./-learning.css:8
./-map-basic.css:75
./-map-group.css:15
./-map.css:0
./-page.css:10
./-reference.css:9
./-select-atts.css:11
./-subject-scheme-map.css:40
./-table-cals.css:41
./-table-html-cals.css:97
./-task.css:26
./-topic-basic.css:31
./-topic-body-lists.css:28
./-topic-body.css:110
./-topic-legacy-conversion.css:6
./-topic-metadata-indexterm.css:17
./-topic-metadata-prolog.css:62
./-topic-related-links-xref.css:28
./-topic-specialization.css:16
./-topic-table-simpletable.css:8
./-topic-table.css:12
./-topic.css:0
./-web-author.css:11

While many of these don't apply to my content (I'm not using many of the DITA technical extensions), many do.

I can look in our FrameMaker structured documents and obtain things like font styles, margins, spacing, and so on. But in addition to applying these, I must also undo the formats I don't want. As examples,

• Our <note> prefix isn't boldfaced, but dita/-topic-body.css applies boldface.
• Our table captions aren't boldfaced, but dita/-table-html-cals.css applies boldface.
• I might apply margin to adjust spacing, but the dita CSS applies padding, or vice-versa.

And you are right, the dita CSS files often use different selectors with different specificities, such that I need to undo something in one way, but then I apply the desired property in another way. My CSS file is somewhat difficult to follow because of this.

I think what I might do is collect all of the dita CSS "undoing" actions in a separate file that I include from my own CSS file, then my own CSS file is a concise description of the editor and output styling that others in my team can more easily maintain. I might even try writing a perl script to create this programmatically. I'll spend some time on this and share how it goes!

[Costin]

Hi Chris,

That sounds like a good plan.

However, as you specified that the users are also working with the Author view, in order to obtain the same results also in the output (for the PDF to look similar to the Author view), I would like to add that you should use the DITA Map PDF based on CSS only scenario.
That scenario is deprecated but you can add it manually from the "Configure Transformation Scenario(s)" dialog > New > DITA OT transformation > choose PDF (CSS Formatter - Deprecated).

Regards,
Costin

[chrispitude]

Hi Costin,

The "HTML5 & CSS" PDF transformation is PDF Chemistry, right? If so, I want to use that to take advantage of all the development work you're putting into it. I am a strong believer that CSS-based PDF creation is the way for us to go, especially with the powerful extensions (xpath, etc.) you're adding to it!

I've created a perl script to process the files in the <OXYGEN_HOME>/frameworks/dita/css/core directory. You give it a perl regex pattern and a list of CSS files, like this:

Code: Select all

get_unset_css.pl '(padding|margin)' ./-colors.css ./-topic-basic.css

and it returns CSS that unsets all the matching properties, with comments to show the previous values:

Code: Select all

@namespace oxy "http://www.oxygenxml.com/extensions/author";
*[class~="topic/abstract"] {
 margin:unset;  /* 0.5em 0 */
}
*[class~="topic/body"] {
 margin:unset;  /* 1em 1em 2em 3px */
}
*[class~="topic/related-links"] {
 margin:unset;  /* 0.5em 0 */
}
*[class~="topic/searchtitle"], *[class~="topic/navtitle"] {
 margin:unset;  /* 0.5em 0 */
}
*[class~="topic/shortdesc"] {
 margin:unset;  /* 0.5em 0 0.5em 3px */
}
*[class~="topic/title"] {
 margin-bottom:unset;  /* 0.2em */
 margin-top:unset;  /* 0.6em */
}
*[class~="topic/topic"] {
 margin:unset;  /* 0.5em */
}
@media print {
 *[class~="topic/topic"] {
  margin-left:unset;  /* 0 */
 }
 *[class~="topic/topic"]  *[class~="topic/topic"] > *[class~="topic/title"] {
  padding-bottom:unset;  /* 1pt */
 }
 *[class~="topic/topic"] > *[class~="topic/title"] {
  padding-bottom:unset;  /* 2pt */
 }
}

I wrote some bash scripting to create "unset" files for the various properties, as I want to step carefully and not throw away useful things:

#!/bin/bash

Code: Select all

css_files='./-bookmap-content.css ./-colors.css ./-conrefs.css ./-domain-hi-d.css ./-domain-pr-d.css ./-domain-sw-d.css ./-domain-ui-d.css ./-glossary-related.css ./-glossary.css ./-group-display-atts.css ./-i18n-de.css ./-i18n-en.css ./
-i18n-fr.css ./-map-basic.css ./-map-group.css ./-page.css ./-select-atts.css ./-subject-scheme-map.css ./-table-cals.css ./-table-html-cals.css ./-topic-basic.css ./-topic-body-lists.css ./-topic-body.css ./-topic-related-links-xref.css
 ./-topic-specialization.css ./-topic-table-simpletable.css ./-topic-table.css'

patterns="font content margin padding color border decoration"

for pattern in $patterns
do
  get_unset_css.pl "$pattern" $css_files > unset_${pattern}.css
done

This gives me a nice set of "unset" files to try:

Code: Select all

$ ls -l unset*
-rw-rw-rw- 1 chrispy chrispy 12745 May  6 12:05 unset_border.css
-rw-rw-rw- 1 chrispy chrispy  6856 May  6 12:05 unset_color.css
-rw-rw-rw- 1 chrispy chrispy 69356 May  6 12:05 unset_content.css
-rw-rw-rw- 1 chrispy chrispy  1643 May  6 12:05 unset_decoration.css
-rw-rw-rw- 1 chrispy chrispy 10180 May  6 12:05 unset_font.css
-rw-rw-rw- 1 chrispy chrispy  6234 May  6 12:05 unset_margin.css
-rw-rw-rw- 1 chrispy chrispy  3894 May  6 12:05 unset_padding.css

I tried @importing the padding and margin files at the top of my own alternate CSS file, and it does seem to get rid of various problematic behaviors. (Now I need to go find all the manual overrides in my CSS file and remove them, since they're programmatically unset via these files!)

I'll tread more carefully with the remaining properties though...

[chrispitude]

I found a good way to apply formats separately to the authoring window and to PDF Chemistry (where needed).

For whatever reasons, table borders want to be applied to the <table> element in the HTML (and thus in the PDF) and to the <tgroup> element in the authoring window. (If I apply them to <table> in the editing window, the top and bottom borders extend full-page horizontally, which is not correct.)

I found the [id]:root and html:root selectors to differentiate well between the authoring window and HTML documents:

Code: Select all

[id]:root *[class~='topic/tgroup'],  /* authoring window */
html:root *[class~='topic/table'] {  /* intermediate HTML document */
  border-top-style : solid ;
  border-bottom-style : solid ;
  border-top-width : thin ;
  border-bottom-width : thin ;
}

These selectors are nice and compact. I decided to use them anywhere that a CCS construct should apply to one side but not the other, which makes the CSS more self-documenting.

[chrispitude]

The "unset" file approach fixes some things (like padding and margins), but I still find myself fighting things in the built-in CSS files. For example, there are lots of properties in "dita/css/print/p-numbering-shallow.css" that are defined with !important, which require me to precisely write selectors to override them.

For example, we want to control titles separately for our preface, chapters, appendixes, and glossary. The following default CSS is proving difficult:

Code: Select all

/*
        Topics from Front Matter and Back Matter and
        all other topics that follow a part
        should not define string sets, counters, etc..
*/
*[class ~= "bookmap/frontmatter"] > *[class ~= "topic/title"]:before,
*[class ~= "bookmap/frontmatter"] *[class ~= "topic/topic"] > *[class ~= "topic/title"]:before,
*[class ~= "bookmap/backmatter"] > *[class ~= "topic/title"]:before,
*[class ~= "bookmap/backmatter"] *[class ~= "topic/topic"] > *[class ~= "topic/title"]:before,
*[class ~= "topic/topic"][is-part] ~ *[class ~= "topic/topic"]:not([is-part]) > *[class ~= "topic/title"]:before,
*[class ~= "topic/topic"][is-part] ~ *[class ~= "topic/topic"]:not([is-part]) *[class ~= "topic/topic"] > *[class ~= "topic/title"]:before{
    content:none !important;

Some of our books use <part> and some don't. But because of the selector above being defined with !important, I am required to multiply out part and no-part variations of equivalent selectors, otherwise written precisely as above, to override them.

And there are many more cases like this.

I find that:

• I spend more time fighting the default CSS than applying my own styles.
• Our resulting CSS file (that my team must maintain) is more complicated and less clear than it would otherwise be

Oxygen folks - is there a way to run Chemistry PDF with only my CSS applied? I will gladly take responsibility for all counters, page and elements formats, etc.

I've seen other folks on here mention that they've resorted to modifying the default PDF Chemistry CSS files instead of fighting them, so I know I'm not the only one. But I'd prefer a cleaner solution than that.

[chrispitude]

Good progress! I copied the <OXYGEN_HOME>/frameworks/dita/css/core/ folder to my own project directory and called it core_modified/, then I wrote a perl script to modify those files to comment out all the visual formatting stuff:

Code: Select all

#!/usr/bin/perl
#
# run it like this:
#
#  ./comment_stuff.pl ./core_modified/*.css

use warnings;
use strict;

while (my $filename = shift) {
 my $origfile = my $file = readfile($filename);
 $file =~ s!^([ \t]+margin(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+padding(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+text-align(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+border(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+font(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+content(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 $file =~ s!^([ \t]+color(-[\w\-]+)?:.*;) *(\r?)$!/*$1 - MODIFIED*/$3!mg;
 if ($file ne $origfile) {
  print "Writing '$filename'...\n";
  writefile($filename, $file);
 }
}

sub readfile {
 my $filename = shift;
 open(EXISTING_FILE, "<$filename") or die "Can't open '$filename' for input: $!";
 local $/ = undef;
 binmode(EXISTING_FILE, ":encoding(utf-8)");
 my $existing_content = <EXISTING_FILE>;
 close EXISTING_FILE;
 return $existing_content;
}

sub writefile {
 my ($filename, $new_content) = @_;
 open(FILE, ">$filename") or die "Can't open '$filename' for output: $!";
 binmode(FILE, ":encoding(utf-8)");
 print FILE $new_content;
 close FILE;
}

(There is one nested comment in -subject-scheme-map.css that must be fixed manually.)

I then @import core_modified/-dita.css from my own master CSS file and I add the CSS to my project as a full CSS file rather than an alternate file. The good news is, this works great in the editor!! All the formats I'm fighting are gone, but all the non-visual counter machinery and such are still present.

Now if I can figure out how to invoke PDF Chemistry with only my own CSS files and *not* the built-in CSS files, I think I'll be in good shape.

Once I get everything working, I'll share a sample Oxygen project so you can play with the solution yourself.

[Dan]

Oxygen folks - is there a way to run Chemistry PDF with only my CSS applied? I will gladly take responsibility for all counters, page and elements formats, etc.

No, there is no such option. You can try to change the build.xml file from the com.oxygenxml.pdf.css DITA plugin.

Many regards,
Dan

[chrispitude]

To summarize my findings so far...

The XML Author editing window applies CSS files from the following location:

Code: Select all

<OXYGEN_HOME>/frameworks/dita/css/core/

The PDF Chemistry publishing pipeline applies CSS files from the following locations:

Code: Select all

<OXYGEN_HOME>/frameworks/dita/css/print/
<OXYGEN_HOME>/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/app/
<OXYGEN_HOME>/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.editlink/

If you're fighting properties in the editing files, that's easy to resolve - just use the perl script I posted on 5/8/2019 to create a core_modified/ set of CSS files, and define that as the CSS style (full, not alternative) used for the editing window.

The PDF Chemistry pipeline is proving more difficult to override. I'm fighting some visual things, some content definitions, and a counter reset that we don't want. The PDF Chemistry CSS files are defined in com.oxygenxml.pdf.css/build.xml:

Code: Select all

<property name="dita.print.css" value="${default.css.dir.abs.path}/print/p-dita.css"/>
<property name="webhelp.topic.css" value="${dita.plugin.com.oxygenxml.webhelp.responsive.dir}/oxygen-webhelp/app/topic-page-print.css"/>

and in build-extensions.xml:

Code: Select all

<property xmlns:dita="http://dita-ot.sourceforge.net" name="extension.css" value="${dita.plugin.com.oxygenxml.editlink.dir}/pdf-css.css"/>

The next step is to identify exactly which constructs I want to override and where they're located, then decide how to proceed from there.

[chrispitude]

More progress! There are three PDF Chemistry parameters that I can set to specify these files. So, I created a small script to make my own copy of these four folders:

Code: Select all

#!/bin/bash
OXYGEN=/mnt/c/Program\ Files/Oxygen\ XML\ Author\ 21.0/
rm -rf ./css_core ./css_print ./css_webhelp ./css_editlink
cp -R "${OXYGEN}/frameworks/dita/css/core/" ./css_core
cp -R "${OXYGEN}/frameworks/dita/css/print/" ./css_print
cp -R "${OXYGEN}/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.webhelp.responsive/oxygen-webhelp/app/" ./css_webhelp
cp -R "${OXYGEN}/frameworks/dita/DITA-OT3.x/plugins/com.oxygenxml.editlink/" ./css_editlink
./comment_stuff.pl ./css_core/*.css
./comment_stuff.pl ./css_editlink/*.css
./comment_stuff.pl ./css_print/*.css
./comment_stuff.pl ./css_webhelp/*.css ./css_webhelp/*/*.css

Then I set the following four parameters in my PDF Chemistry transformation:

Code: Select all

args.css = ${pd}/prj/css/synopsys.css
dita.print.css = ${pd}/prj/css/css_print/p-dita.css	
extension.css = ${pd}/prj/css/css_editlink/pdf-css.css
webhelp.topic.css = ${pd}/prj/css/css_webhelp/topic-page-print.css

So what's the magic in the comment_stuff.pl script? Well right now, there's no magic; just a bunch of super hacky regex transformations. For example,

Code: Select all

./css_core/-i18n-en.css

contains lots of things I want to keep (display of metadata content in the editor) and lots of things I want to comment out (note prefixes, abstract prefixes). I want to create a user-friendly method of specifying what to keep and comment out in each file. That way, each time there's a new release of Oxygen XML, I can just run the script to get the latest and greatest CSS files comment to my needs. I'll share more when I come up with it.

But even as it is, this approach is working wonderfully. Now that I am not fighting existing CSS constructs, (1) my CSS file has gotten much simpler, and (2) it works equally well in the editor and for generating a PDF in PDF Chemistry.

[chrispitude]

I learned some things today while trying to implement cross-reference styles in CSS.

1. The content: CSS property differs between web browsers, the XML Author editing window, and PDF Chemistry as follows:

• In a web browser, content: cannot override the content of an element; it can only prepend or append content using the ::before and ::after qualifiers.
• In XML Author and in PDF Chemistry, you can override the content of an element itself (as well as use ::before and ::after to prepend or append).

2. PDF Chemistry does not support the oxy_link-text() function in a content specification. If you use it, the specification is discarded in the output PDF, even though it works in the editor.

3. oxy_link-text() does not work in the browser. However, the merged HTML always has the link target name present inside a cross-reference as existing text content:

Code: Select all

<a class="- topic/xref xref x_table" href="#id3" outputclass="x_table" type="table">
  Table 
  <span class="- topic/ph ph table--title-label-number " outputclass="table--title-label-number ">1</span>
  <span class="- topic/ph ph table--title-label-number-placeholder " outputclass="table--title-label-number-placeholder " href="#unique_23_Connect_42_CEGJCFDGJ6"></span>
  : This is a Table With A Long-ish Title</a>
 <!-- ^^^^^  note the actual link target title in the HTML here -->

You can override this content in the editor and final output PDF, but not in the browser due to #1 above.

Initially I tried to style my chapter references like this, to put the name of the chapter in quotes:

Code: Select all

*[class~='topic/xref'][href][outputclass~="x_chapter"] {
    content: "Chapter " target-counter(attr(href), chapter) ', "' oxy_link-text() '"';
}

This would have been a nice clean solution. However, it failed due to #2 above. I ended up having to split it into prepend and append pieces:

Code: Select all

*[class~='topic/xref'][href][outputclass~="x_chapter"]::before {
    content: "Chapter " target-counter(attr(href), chapter) ', "';
}
*[class~='topic/xref'][href][outputclass~="x_chapter"]::after {
    content: '"';
}

which works in the editor and output PDF (but not in the browser viewing the merged HTML, but that's okay because the writers don't look at that).

[chrispitude]

I needed a more fine-grained way to comment CSS constructs in the Oxygen CSS files. I wrote a perl script that lets you control what to comment (or not comment) on a per-file, per-selector, and per-property basis.

comment_v0.1.tgz

(3.21 KiB) Downloaded 71 times

The script is configured by an array of entries, where each entry has four items:

• flag - what action to take
• CSS file basename regex (no directory name)
• selector regex
• property regex

The regexes are quoted with qr{}. An empty regex matches everything. A flag value of 1 indicates to comment matching entries, a flag value of 0 means not to comment them, and a flag value of 2 means to report the matching entries. The entries are applied in order; the last matching flag value wins.

For example, the following configuration comments all margin* and padding* properties, except those in p-side-notes.css:

Code: Select all

my @patterns = (
# comment flag (0==no, 1==yes, 2==print)
# |   base filename
# |   |       selector pattern
# |   |       |        property pattern
# |   |       |        |
 [1,  qr{},   qr{},   qr{^(margin|padding)}],
 [0,  qr{^p-side-notes},   qr{},   qr{^(margin|padding)}],
);

Using this approach, I'm able to precisely comment out the Oxygen CSS constructs that interfere with editor and print configuration (such as properties applied with !important that are difficult to unapply), while keeping as many helpful default properties as possible.

If you're unsure what a particular entry would apply to, set the flag to 2 and the script will report all the matching CSS constructs for those entries.

I'm also including the bash shell script I use to run it. Basically my workflow is as follows:

• Run the bash script, which builds new commented files from the original Oxygen CSS files.
• Publish a PDF with PDF Chemistry.
• Use Chrome's CSS Inspector to identify applicable Oxygen properties I want to comment out.
• Modify the commenting configuration to include them.
• Rerun from step 1.

[chrispitude]

I was able to eliminate the need for both full and incremental styles in the Style drop-down menu by (1) creating a synopsys_core.css file:

Code: Select all

@import "css_core/-dita.css";
@import "synopsys.css";

I then point to synopsys_core.css as a full (non-alternate) CSS file in the Style menu, and I point to synopsys.css in the PDF Chemistry configuration.