Re: [XXE] Allow end-users to override (and copy) the CSS stylesheet

[nobili, philippe]

Dear M. Shafie,

Many thanks for the detailed information, that's great.
We already have the customized configurations in place (DocBook 4 and 5), it 
should be fairly straightforward for us to  follow this route and finish the 
work... :).

Best regards.


Philippe Nobili
Subsurface Imaging - Product Engineering
Tel: +33 16447 4090 | Mobile: +33 63756 6441

CGG,
27 avenue Carnot
Massy, 91341 - France
http://www.cgg.com

Please consider the environment before printing.


-Original Message-
From: Hussein Shafie [mailto:huss...@xmlmind.com]
Sent: Friday, December 02, 2016 10:49 AM
To: nobili, philippe
Cc: 'xmleditor-support@xmlmind.com'
Subject: Re: [XXE] Allow end-users to override (and copy) the CSS stylesheet

On 11/30/2016 06:22 PM, nobili, philippe wrote:
>
>
>
> For a couple of years we have been using our own DocBook
> customizations, with specialized PDF/Webhelp and HTML output styles.
> These customization are bundled within XXE internally for our users.
>
>
>
> For HTML/Webhelp rendering, we would need some extra flexibility: for
> some products/projects, deliver a customized copy of our stock CSS
> (which is copied during the document conversion process).
>
>
>
> We are wondering what you be **the simplest way** to provide this
> feature to our users, ideally just a parameter they could set in XXE
> GUI during documentation conversion and holding the name of their
> customized CSS...  We know of course how to do this using a personal XXE
> customization, but it is not really practical here.
>
>
>

My answer assumes that you are authoring DocBook 5 documents but the same 
approach applies to DocBook 4 (or DITA).

How to achieve what you want for a group of users is not well documented, if at 
all. Sorry for that.

Let's see step by step what to do:

1) Create a directory in the XXE_user_preferences_dir/addon/. Let's call this 
directory sample_customize_docbook5/. This directory is intended to contain all 
your customizations of the DocBook v5+ configuration.

("XXE_user_preferences_dir" is explained here
http://www.xmlmind.com/xmleditor/_distrib/doc/configure/anatomy_of_a_config.html#xxe_user_preferences_dir)

2) Create in sample_customize_docbook5/ a configuration file called 
0docbook5.xxe

As explained in "XMLmind XML Editor - Configuration and Deployment, 5.
Customizing an existing configuration"
(http://www.xmlmind.com/xmleditor/_distrib/doc/configure/customizing.html),
this file must contain:

---
http://www.xmlmind.com/xmleditor/schema/configuration";
   xmlns:cfg="http://www.xmlmind.com/xmleditor/schema/configuration";
   xmlns:db="http://docbook.org/ns/docbook";
   xmlns:svg="http://www.w3.org/2000/svg";
   xmlns:xi="http://www.w3.org/2001/XInclude";
   xmlns:xlink="http://www.w3.org/1999/xlink";
   xmlns:html="http://www.w3.org/1999/xhtml";>

   


---

3) Create in sample_customize_docbook5/ one or more CSS files customizing the 
WebHelp output.

It's possible to completely restyle the WebHelp output or to refer to the stock 
style as follows:

---
@import (__stock_webhelp.css);

h1,
h2,
h3,
h4,
h5,
h6 {
 color: #80;
 border-bottom: 1px solid #80;
 padding-bottom: 0.25em;
}
---

Let's call the above custom CSS file maroon_webhelp.css.

To make things even clearer, I've also created a second custom CSS file called 
navy_webhelp.css:

---
@import (__stock_webhelp.css);

h1,
h2,
h3,
h4,
h5,
h6 {
 color: #80;
 border-bottom: 3px double #80;
 padding-bottom: 0.25em;
}
---


4) Now let's tell XXE about these custom CSS files for use for WebHelp output. 
This is done by adding these properties in 
sample_customize_docbook5/0docbook5.xxe

---
   

   Maroon, underlined, headings 
maroon_webhelp.css Navy, underlined, headings navy_webhelp.css

   

   maroon_webhelp.css
---

5) Delete XXE_user_preferences_dir/cache/ to be sure that XXE will see your 
sample_customize_docbook5/

6) Start XXE and open a DocBook 5 document. Select "Options|Customize
Configuration|Customize Document Conversion Stylesheets" (see
http://www.xmlmind.com/xmleditor/_distrib/doc/help/ConversionStylesheetsEditor_reference.html).
Then select "Convert to Web Help".

You'll see attached screenshot1.png.

The end user may now select the CSS file she/he prefers from the "CSS 
stylesheet" comboxbox. See screenshot2.png.

After that, there is nothing else for the end user to do (I mean, CSS file 
copies to Web Help output directory is automatic). Moreover, the CSS choice 
made by the end user is persistent across editing sessions.

Please find attached to this email sample_customize_docbook5.tar.gz which will 
let you experiment with this facility.



---
PS: There are probably other ways to achieve what you want (e.g.
 as explained in
http://www

Re: [XXE] Allow end-users to override (and copy) the CSS stylesheet

[Hussein Shafie]

On 11/30/2016 06:22 PM, nobili, philippe wrote:




For a couple of years we have been using our own DocBook customizations,
with specialized PDF/Webhelp and HTML output styles.  These
customization are bundled within XXE internally for our users.



For HTML/Webhelp rendering, we would need some extra flexibility: for
some products/projects, deliver a customized copy of our stock CSS
(which is copied during the document conversion process).



We are wondering what you be **the simplest way** to provide this
feature to our users, ideally just a parameter they could set in XXE GUI
during documentation conversion and holding the name of their customized
CSS…  We know of course how to do this using a personal XXE
customization, but it is not really practical here.





My answer assumes that you are authoring DocBook 5 documents but the 
same approach applies to DocBook 4 (or DITA).


How to achieve what you want for a group of users is not well 
documented, if at all. Sorry for that.


Let's see step by step what to do:

1) Create a directory in the XXE_user_preferences_dir/addon/. Let's call 
this directory sample_customize_docbook5/. This directory is intended to 
contain all your customizations of the DocBook v5+ configuration.


("XXE_user_preferences_dir" is explained here 
http://www.xmlmind.com/xmleditor/_distrib/doc/configure/anatomy_of_a_config.html#xxe_user_preferences_dir)


2) Create in sample_customize_docbook5/ a configuration file called 
0docbook5.xxe


As explained in "XMLmind XML Editor - Configuration and Deployment, 5. 
Customizing an existing configuration" 
(http://www.xmlmind.com/xmleditor/_distrib/doc/configure/customizing.html), 
this file must contain:


---
http://www.xmlmind.com/xmleditor/schema/configuration";
  xmlns:cfg="http://www.xmlmind.com/xmleditor/schema/configuration";
  xmlns:db="http://docbook.org/ns/docbook";
  xmlns:svg="http://www.w3.org/2000/svg";
  xmlns:xi="http://www.w3.org/2001/XInclude";
  xmlns:xlink="http://www.w3.org/1999/xlink";
  xmlns:html="http://www.w3.org/1999/xhtml";>

  


---

3) Create in sample_customize_docbook5/ one or more CSS files 
customizing the WebHelp output.


It's possible to completely restyle the WebHelp output or to refer to 
the stock style as follows:


---
@import (__stock_webhelp.css);

h1,
h2,
h3,
h4,
h5,
h6 {
color: #80;
border-bottom: 1px solid #80;
padding-bottom: 0.25em;
}
---

Let's call the above custom CSS file maroon_webhelp.css.

To make things even clearer, I've also created a second custom CSS file 
called navy_webhelp.css:


---
@import (__stock_webhelp.css);

h1,
h2,
h3,
h4,
h5,
h6 {
color: #80;
border-bottom: 3px double #80;
padding-bottom: 0.25em;
}
---


4) Now let's tell XXE about these custom CSS files for use for WebHelp 
output. This is done by adding these properties in 
sample_customize_docbook5/0docbook5.xxe


---
  

  Maroon, underlined, headings
maroon_webhelp.css
Navy, underlined, headings
navy_webhelp.css

  

  maroon_webhelp.css
---

5) Delete XXE_user_preferences_dir/cache/ to be sure that XXE will see 
your sample_customize_docbook5/


6) Start XXE and open a DocBook 5 document. Select "Options|Customize 
Configuration|Customize Document Conversion Stylesheets" (see 
http://www.xmlmind.com/xmleditor/_distrib/doc/help/ConversionStylesheetsEditor_reference.html). 
Then select "Convert to Web Help".


You'll see attached screenshot1.png.

The end user may now select the CSS file she/he prefers from the "CSS 
stylesheet" comboxbox. See screenshot2.png.


After that, there is nothing else for the end user to do (I mean, CSS 
file copies to Web Help output directory is automatic). Moreover, the 
CSS choice made by the end user is persistent across editing sessions.


Please find attached to this email sample_customize_docbook5.tar.gz 
which will let you experiment with this facility.




---
PS: There are probably other ways to achieve what you want (e.g. 
 as explained in 
http://www.xmlmind.com/xmleditor/_distrib/doc/configure/customize_html_css.html) 
but what's explained here is the cleanest way to do it and also the 
nicest to use by the end user. Moreover the explained method is 
guaranteed to survive XXE upgrades.








sample_customize_docbook5.tar.gz
Description: application/gzip

--
XMLmind XML Editor Support List
xmleditor-support@xmlmind.com
http://www.xmlmind.com/mailman/listinfo/xmleditor-support

[XXE] Allow end-users to override (and copy) the CSS stylesheet

[nobili, philippe]

Dear M. Shafie,

For a couple of years we have been using our own DocBook customizations, with 
specialized PDF/Webhelp and HTML output styles.  These customization are 
bundled within XXE internally for our users.

For HTML/Webhelp rendering, we would need some extra flexibility: for some 
products/projects, deliver a customized copy of our stock CSS (which is copied 
during the document conversion process).

We are wondering what you be *the simplest way* to provide this feature to our 
users, ideally just a parameter they could set in XXE GUI during documentation 
conversion and holding the name of their customized CSS...  We know of course 
how to do this using a personal XXE customization, but it is not really 
practical here.

Many thanks for your advises.
Best regards,
Philippe.

[cggsigbanner]
Philippe Nobili
Subsurface Imaging - Product Engineering
Tel: +33 16447 4090 | Mobile: +33 63756 6441

CGG,
27 avenue Carnot
Massy, 91341 - France
http://www.cgg.com

Please consider the environment before printing.

This email and any accompanying attachments are confidential. If you received 
this email by mistake, please delete
it from your system. Any review, disclosure, copying, distribution, or use of 
the email by others is strictly prohibited.

--
XMLmind XML Editor Support List
xmleditor-support@xmlmind.com
http://www.xmlmind.com/mailman/listinfo/xmleditor-support