Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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...
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:"; }
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>
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
-
- Posts: 846
- Joined: Mon Dec 05, 2011 6:04 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
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
oXygen XML Editor and Author Support
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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
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.
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!
-
- Posts: 846
- Joined: Mon Dec 05, 2011 6:04 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
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
oXygen XML Editor and Author Support
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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
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 */
}
}
#!/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
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'll tread more carefully with the remaining properties though...
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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 ;
}
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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;
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
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.
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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;
}
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.
-
- Posts: 501
- Joined: Mon Feb 03, 2003 10:56 am
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
No, there is no such option. You can try to change the build.xml file from the com.oxygenxml.pdf.css DITA plugin.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.
Many regards,
Dan
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
The XML Author editing window applies CSS files from the following location:
Code: Select all
<OXYGEN_HOME>/frameworks/dita/css/core/
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/
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"/>
Code: Select all
<property xmlns:dita="http://dita-ot.sourceforge.net" name="extension.css" value="${dita.plugin.com.oxygenxml.editlink.dir}/pdf-css.css"/>
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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
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
Code: Select all
./css_core/-i18n-en.css

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.
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
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).
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 -->
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() '"';
}
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: '"';
}
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
- flag - what action to take
- CSS file basename regex (no directory name)
- selector regex
- property regex
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)}],
);
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.
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
Code: Select all
@import "css_core/-dita.css";
@import "synopsys.css";
-
- Posts: 922
- Joined: Thu May 02, 2019 2:32 pm
Re: Sharing CSS files between authoring window and Chemistry PDF (and WebHelp HTML5?)
Post by chrispitude »
I abandoned this approach; it was too complicated to maintain. Instead of disabling Oxygen's CSS rules in scripting in a custom full CSS style file, I will instead apply media-specific rules to modify the default CSS in incremental (alternate) CSS style files:
Code: Select all
@media oxygen {
/* implement our editor overrides like normal people do */
}
@media print {
/* implement our PDF Chemistry overrides like normal people do */
}
Return to “DITA (Editing and Publishing DITA Content)”
- Oxygen XML Editor/Author/Developer
- ↳ Feature Request
- ↳ Common Problems
- ↳ DITA (Editing and Publishing DITA Content)
- ↳ SDK-API, Frameworks - Document Types
- ↳ DocBook
- ↳ TEI
- ↳ XHTML
- ↳ Other Issues
- Oxygen XML Web Author
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Content Fusion
- ↳ Feature Request
- ↳ Common Problems
- Oxygen JSON Editor
- ↳ Feature Request
- ↳ Common Problems
- Oxygen PDF Chemistry
- ↳ Feature Request
- ↳ Common Problems
- Oxygen Feedback
- ↳ Feature Request
- ↳ Common Problems
- Oxygen XML WebHelp
- ↳ Feature Request
- ↳ Common Problems
- XML
- ↳ General XML Questions
- ↳ XSLT and FOP
- ↳ XML Schemas
- ↳ XQuery
- NVDL
- ↳ General NVDL Issues
- ↳ oNVDL Related Issues
- XML Services Market
- ↳ Offer a Service