Date   

DITA Open Toolkit Day recordings #DITA-OT #conferences #Oxygen

Radu Coravu
 

Hi everyone,

We made available all the presentation recordings and slides from the DITA Open Toolkit Day 2019 which was held in Brussels a couple of weeks ago:

https://www.oxygenxml.com/events/2019/dita-ot_day.html

Hope you will enjoy them.
Thanks to the presenters and the audience for making it a successful event.

Regards,
Radu

Radu Coravu
<oXygen/> XML Editor
http://www.oxygenxml.com


Re: Handle cross-book xrefs in large book collections? #linking

Chris Papademetrious
 

Replying to a previous discussion...

Radu provided me with a DITA-OT plugin that preserves @keyref information in <xref> elements when publishing to xhtml or html5:

<p class="p">You can also see <span class="xref" origkeyref="B.topic_B">this topic in book B</span> and <span class="xref" origkeyref="C.topic_C">this topic in book C</span>.</p>

This is half the solution - so far so good! Now I need to push and preserve the @keys value (including any nested scopes) from the topicrefs into the final XHTML or HTML5 output. This preservation must handle nested subtopic references (within a topic file):

   <topicref href="topic_C.dita" keys="topic_C">
     <topicref href="topic_C.dita#id_C_subtopic" keys="topic_C_subtopic"/>
   </topicref>

and preserve it something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="copyright" content="(C) Copyright 2019" />
<meta name="DC.rights.owner" content="(C) Copyright 2019" />
<meta name="DC.type" content="topic" />
<meta name="DC.title" content="Topic in Book C" />
<meta name="DC.relation" scheme="URI" content="topic_C.html#id_C_subtopic" />
<meta name="DC.format" content="XHTML" />
<meta name="DC.identifier" content="id_C" />
<link rel="stylesheet" type="text/css" href="commonltr.css" />
<title>Topic in Book C</title>
</head>
<body id="id_C" @origkeys="topic_C">
   <h1 class="title topictitle1" id="ariaid-title1">Topic in Book C</h1>
   <div class="body">
      <p class="p">Welcome to the topic in book C!</p>
      <p class="p">You can also see <span class="xref" origkeyref="A.topic_A">this topic in book A</span> and <span class="xref" origkeyref="B.topic_B">this topic in book B</span>.</p>
   </div>
   <div class="related-links">
<ul class="ullinks">
<li class="link ulchildlink"><strong><a href="topic_C.html#id_C_subtopic">Subtopic in Book C</a></strong><br />
</li>
</ul>
</div><div class="topic nested1" aria-labelledby="ariaid-title2" id="id_C_subtopic" @origkeys="topic_C_subtopic">
   <h2 class="title topictitle2" id="ariaid-title2">Subtopic in Book C</h2>
   <div class="body"><p class="p">Welcome to the subtopic in book C!</p></div>
   <div class="related-links">
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a class="link" href="topic_C.html">Topic in Book C</a></div>
</div>
</div></div>
</body>
</html>

As long as the @keys information is preserved in the output instances, my post-processing script can match the cross-book <xref> elements to the correct instances in the published output files. If we can figure this out, I think we'll have a basic generalized capability for cross-book links (via post-processing) that anyone could use.

My current solution requires the map files to make the connections. This is overly restrictive, plus it assumes the output file structure always matches the DITA topic file structure, which might not always hold true. With the @keys values preserved in the output instances, both these restrictions disappear and the solution becomes generalized.

If someone can at least point me to the right extension point and template to work with, I'd greatly appreciate it!

 - Chris


Re: Page and Column breaks #PDF

Liz Fraley
 

I'm with Corinna - that depends greatly on your toolset. And although I use a different one than she does (which also can do that), I like both her tool and mine.


On Tue, Nov 26, 2019 at 9:06 AM Corinna Kinchin <ckinchin@...> wrote:
Hi John,

If I'm understanding correctly, the MiramoPDF DITA-OT plugin can do everything you and Chris would like, for example by using one of the supported @outputclass values to force a page break, or to keep with next/previous document object. No need for parsing area trees unless it's something you particularly enjoy ;)

(disclaimer: I work for Datazone, the creators of the MiramoPDF publishing tool)


Re: Why use conref instead of conkeyref? #conref

Julio J Vazquez
 

I tend to use conref for cases where reuse is internal to a single topic, where the overhead of seeing up a key is really not needed. I use the this topic structure to implement. 

That said, I can count the number of times I've done that on one hand because inevitably I discover the object I'm refusing can be used elsewhere.

Julio J. Vazquez 


Re: Why use conref instead of conkeyref? #conref

Mica Semrick
 

Hi,

You should use a conref where the language does not need to vary per publication. For example, if your legal department approves a set of caution and warnings that should not change.

If you use conkeyref everywhere, you may end up with extra work recreating the key map for every publication.

I've also generally found that indirect linking is quite challenging for most authors to wrap their minds around.

- m


On November 26, 2019 3:13:12 PM PST, Jonathan Hanna <jhanna@...> wrote:
Being new to DITA, I am trying to understand cases where conref should be used instead of conkeyref. As far as I can tell, conkeyref can do anything conref can do with the added benefit of indirect addressing. The only advantage I can see to conref is that it is more straightforward to use since it does not require a keydef in a map.

Is there anything I am missing? Other than ease of use, is there any reason to use conref instead of conkeyref?

Regards,
Jonathan


Re: Page and Column breaks #PDF

Kristen James Eberlein
 

+1 for anything that Jean-luc Doumont has authored or presented. I still remember a presentation that he gave at the first industry conference that I attended!

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 11/26/2019 5:49 PM, Jeff Hooker wrote:
Jean-luc Doumont


Why use conref instead of conkeyref? #conref

Jonathan Hanna
 

Being new to DITA, I am trying to understand cases where conref should be used instead of conkeyref. As far as I can tell, conkeyref can do anything conref can do with the added benefit of indirect addressing. The only advantage I can see to conref is that it is more straightforward to use since it does not require a keydef in a map.

Is there anything I am missing? Other than ease of use, is there any reason to use conref instead of conkeyref?

Regards,
Jonathan


Re: Page and Column breaks #PDF

Jeff Hooker
 

I'm sure lots of folks will respond with ways of getting people onside with accepting the shortcomings of automated publishing, so I'm going to restrict my comment to the other half of the equation.

Take ownership of what you can control: automated layout does inflict some limitations on a document, but it also affords the opportunity to really sweat the details of typography and layout and be sure that no one is going to override your Framemaker template to screw them up. You can fine tune how the same objects appear when they appear in different settings, always striving for maximum transmission of information with minimum noise. Get away from basing the look and feel on what "looks nice" and actually study usability. My favorite book on this subject is Trees, Maps, and Theorems by Jean-luc Doumont. After years of steady development, the output of my CCMS is jewel-like and exudes a degree of quality and consistency that you're never going to see in a Framemaker document. The more immense the document, the more unexpected the beauty of it. Complaining about a page break when confronted with such relentless consistency tends to make one feel rather foolish.


On Mon, Nov 25, 2019 at 7:16 AM John Piechowski <john@...> wrote:
I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could insert a page/column break to force the section header or headline that renders on the bottom of one page to the next page with it's content. Or sometimes there are one or two lines of text left at the bottom on a column that they prefer are with the content on the next column.

Sometimes it is a headline and short paragraph that stays on one page with the image that it references on the next page, making the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly what they wanted using DTP. Now as we promote content reuse, we lost this control without negatively impacting other documents that use the same topic.

We've tried to explain the great benefits we are getting through content reuse: consistency, reduces translation, improved quality. But often, DITA is seen outside the team as a step back in quality.

I'm interested in what others are doing to balance the positive outcome of content reuse against the negative effect document layout.


Re: Page and Column breaks #PDF

Joe Williams
 

At a previous employer, we had a subject matter expert for one particular document who continually sent ad hoc requests for page tweaks constantly, which used up a lot of cycles for the dedicated author and for myself as the XSLT developer for multiple products (in addition to other DITA-related duties). Fortunately, this was a DoD contract and our product manager had me go through the MilSpec to determine under what conditions page breaks and table breaks were to occur. Turns out that the look and feel of the document was specified for every eventuality. 

Maybe your reviewers would be willing to provide such a set of rules or guidelines, so that you can implement them in your publishing setup to achieve those benefits Kris identified. Instead of tweaking repeatedly, maybe you can help them identify rules that govern those tweaks, if that makes sense.


Re: Page and Column breaks #PDF

Corinna Kinchin
 

Hi John,

If I'm understanding correctly, the MiramoPDF DITA-OT plugin can do everything you and Chris would like, for example by using one of the supported @outputclass values to force a page break, or to keep with next/previous document object. No need for parsing area trees unless it's something you particularly enjoy ;)

(disclaimer: I work for Datazone, the creators of the MiramoPDF publishing tool)


Re: Page and Column breaks #PDF

ekimber@contrext.com
 

If you google Tony Graham you should find his Balisage paper on using area tree processing to do automatic fitting of figures.

There are basically two ways to do it:

1. Generate FO, generate area doc, post process it to generate updated XML (or a side file with layout info), process updated XML (or original XML plus side file) to generate new FO and PDF (repeat as needed get to final layout)
2. Use Java XSLT extensions to do on-the-fly rendering of things like tables and figures and then make choices in the XSLT based on the results--this is the technique Tony describes in his paper.

Approach (1) is a true multi-pass process and with it many things are possible. Approach (2) is often called 1 1/2 pass.

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 11/26/19, 9:48 AM, "John Piechowski" <dita-users@groups.io on behalf of john@piechowski.org> wrote:

Kristen - thanks for the advice on a better way to sell the value of it.
Chris - I'll check out your specialization utility. It may give us some of the formatting functionality to get a compromise between efficiency and layout.

Eliot - Thanks for the idea on a multi-pass solution. We use FOP, so we might be able to do something with that as well.

John

On Tue, Nov 26, 2019 at 5:45 AM Kristen James Eberlein <kris@eberleinconsulting.com> wrote:






Hi, John.
I think the point to argue with reviewers who are unhappy with
page breaks is not content reuse, but automation and ability to
scale. I've found that's a much more compelling argument.
Old days
I remember working as a contract information developer at IBM
circa 2003. We'd finished a project release, and I spent two days
finessing the page breaks for a 500+ page installation manual. I'd
insert a page break, kick off a PDF build, and then do something
else for 20 minutes that it took for the PDF to be generated.
Rinse and repeat. Rinse and repeat. Rinse and repeat ...
[The content was authored in SGML (IBMIDDOC), edited in Frame2000
(IBM version of structured Frame), and rendered to PDF using XPP
(often known as XyVision).]

2019
Documentation teams often have their publishing processes
automated. As content is checked into version control or a CCMS,
automated publishing processes are initiated. Up-to-date content
is made available MUCH more frequently than in the days of desktop
publishing. Writers can develop much more content ...

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com <http://www.eberleinconsulting.com>
+1 919 622-1501; kriseberlein (skype)


On 11/25/2019 10:16 AM, John Piechowski
wrote:



I'm guessing many of us using DITA receive similar feedback from
reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could
insert a page/column break to force the section header or headline
that renders on the bottom of one page to the next page with it's
content. Or sometimes there are one or two lines of text left at
the bottom on a column that they prefer are with the content on
the next column.

Sometimes it is a headline and short paragraph that stays on one
page with the image that it references on the next page, making
the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly
what they wanted using DTP. Now as we promote content reuse, we
lost this control without negatively impacting other documents
that use the same topic.

We've tried to explain the great benefits we are getting through
content reuse: consistency, reduces translation, improved quality.
But often, DITA is seen outside the team as a step back in
quality.

I'm interested in what others are doing to balance the positive
outcome of content reuse against the negative effect document
layout.


Re: Page and Column breaks #PDF

John Piechowski
 

Kristen - thanks for the advice on a better way to sell the value of it.

Chris  - I'll check out your specialization utility. It may give us some of the formatting functionality to get a compromise between efficiency and layout.

Eliot - Thanks for the idea on a multi-pass solution. We use FOP, so we might be able to do something with that as well.

John

On Tue, Nov 26, 2019 at 5:45 AM Kristen James Eberlein <kris@...> wrote:

Hi, John.

I think the point to argue with reviewers who are unhappy with page breaks is not content reuse, but automation and ability to scale. I've found that's a much more compelling argument.

Old days

I remember working as a contract information developer at IBM circa 2003. We'd finished a project release, and I spent two days finessing the page breaks for a 500+ page installation manual. I'd insert a page break, kick off a PDF build, and then do something else for 20 minutes that it took for the PDF to be generated. Rinse and repeat. Rinse and repeat. Rinse and repeat ...

[The content was authored in SGML (IBMIDDOC), edited in Frame2000 (IBM version of structured Frame), and rendered to PDF using XPP (often known as XyVision).]

2019

Documentation teams often have their publishing processes automated. As content is checked into version control or a CCMS, automated publishing processes are initiated. Up-to-date content is made available MUCH more frequently than in the days of desktop publishing. Writers can develop much more content ...

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 11/25/2019 10:16 AM, John Piechowski wrote:
I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could insert a page/column break to force the section header or headline that renders on the bottom of one page to the next page with it's content. Or sometimes there are one or two lines of text left at the bottom on a column that they prefer are with the content on the next column.

Sometimes it is a headline and short paragraph that stays on one page with the image that it references on the next page, making the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly what they wanted using DTP. Now as we promote content reuse, we lost this control without negatively impacting other documents that use the same topic.

We've tried to explain the great benefits we are getting through content reuse: consistency, reduces translation, improved quality. But often, DITA is seen outside the team as a step back in quality.

I'm interested in what others are doing to balance the positive outcome of content reuse against the negative effect document layout.


dita-users successfully transferred to Groups.io #admin

Kristen James Eberlein
 

Hi, Chris.

Unfortunately, I don't think it's an option to get Groups.io to get the missing messages. Yahoo! is barely functioning, and so Groups.io currently is not doing any transfers. I'm glad we moved relatively quickly to Groups.io!

If someone wants to compile the missing messages and upload them to dita-users@groups.io, that would be an option.

The cost for a year's premium membership was USD 220. (It doubled between the time I first looked at Groups.io and when I purchased the membership!) This covered the transfer. For now, I'm OK with having my company pay for the membership, but I certainly appreciate your generous offer.

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 11/12/2019 8:52 AM, Chris Papademetrious wrote:
Hi Kris,

Is there someone at groups.io we can contact about getting the missing messages included?

Also, I recall that groups.io is not free (the conversion or annual or both?). I'd be happy to donate to help defray costs. This group has been incredibly helpful to my own work and I'd be happy to support it in return.

 - Chris



On Sat, Nov 9, 2019 at 4:42 AM Kristen James Eberlein <kris@...> wrote:
I just got the formal notice from Groups.io. Hopefully every active
(non-bouncing) subscriber to the list will have gotten an e-mail.

It looks as if the most recent messages (between 12 October 2019 and
today) were not transferred.

Please stop posting to the old address (dita-users@...) and
begin posting to dita-users@groups.io.

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)





Re: Page and Column breaks #PDF

Kristen James Eberlein
 

Hi, John.

I think the point to argue with reviewers who are unhappy with page breaks is not content reuse, but automation and ability to scale. I've found that's a much more compelling argument.

Old days

I remember working as a contract information developer at IBM circa 2003. We'd finished a project release, and I spent two days finessing the page breaks for a 500+ page installation manual. I'd insert a page break, kick off a PDF build, and then do something else for 20 minutes that it took for the PDF to be generated. Rinse and repeat. Rinse and repeat. Rinse and repeat ...

[The content was authored in SGML (IBMIDDOC), edited in Frame2000 (IBM version of structured Frame), and rendered to PDF using XPP (often known as XyVision).]

2019

Documentation teams often have their publishing processes automated. As content is checked into version control or a CCMS, automated publishing processes are initiated. Up-to-date content is made available MUCH more frequently than in the days of desktop publishing. Writers can develop much more content ...

Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

On 11/25/2019 10:16 AM, John Piechowski wrote:
I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could insert a page/column break to force the section header or headline that renders on the bottom of one page to the next page with it's content. Or sometimes there are one or two lines of text left at the bottom on a column that they prefer are with the content on the next column.

Sometimes it is a headline and short paragraph that stays on one page with the image that it references on the next page, making the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly what they wanted using DTP. Now as we promote content reuse, we lost this control without negatively impacting other documents that use the same topic.

We've tried to explain the great benefits we are getting through content reuse: consistency, reduces translation, improved quality. But often, DITA is seen outside the team as a step back in quality.

I'm interested in what others are doing to balance the positive outcome of content reuse against the negative effect document layout.


Re: Looking for more modern alternatives to Eclipsehelp Infocenters #content-delivery #next-generation

Harald Hermann
 

Hello Jeff,

 

we use Eclipse help for ~10 years and were always hoping that the Eclipse community is adding more features or updates the Eclipse infocenter.

 

As this was not their priority we (Holger Voormann and myself) started a prototype on our own of a modernized Eclipse help web UI.

The target is to improve the search results and to make it mobile ready.

 

We suggested it to Eclipse by responding to Eclipse bug 501718.

The feedback from the Eclipse platform team at the EclipseCon Europe 2019 was also positive and the platform team said they are willing to integrate it once we are ready and the reviews are completed.

 

The prototype is still work in progress but published on https://github.com/howlger/Eclipse-Help-Modernized/

 

Best regards,

Harald

 

 

 

advantest

 

Harald Hermann

 

Advantest Europe GmbH

Branch / Zweigniederlassung Boeblingen

Herrenberger Str. 130

71034 Boeblingen

Germany

Phone: +49-7031-4357-348

Fax:     +49-7031-4357-492

www.advantest.de

 

Advantest Europe GmbH

Managing Directors / Geschaeftsfuehrer: Hans-Juergen Wagner, Michael Stichlmair, Juergen Serrer, Peter Wewerka; Kimiya Sakamoto

Chairman of the Supervisory Board / Vorsitzender des Aufsichtsrats: Atsushi Fujita

Commercial Court / Handelsregister: Muenchen HRB 71083, Seat / Sitz: Muenchen

 

Disclaimer

"This e-mail and any attachments are confidential and may be subject to legal or some other professional privilege. They are intended solely for the attention and use of the named addressee(s). If you are not the named addressee(s) you must not use, disclose, retain or reproduce all or any part of the information contained in this e-mail or any attachments. Any unauthorised use or disclosure may be unlawful. If you have received this e-mail by mistake, please inform the sender immediately and delete it and all copies from your system and destroy any hard copies of it."

 

Think of the environment before you print this email.

 


Re: Page and Column breaks #PDF

despopoulos_chriss
 

John says, "I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents...."

For quite some time we used FrameMaker to publish our PDFs.  That's right...  Generate a FrameMaker book, then manually paginate.  This is really the only (affordable) way to get exquisite page breaks. The range of decisions is just too great to devise a general approach.  As Eliot points out, it depends on page format, document design, styles, and even the type of content (tables, lists, etc.). 

In a previous life I implemented a FrameMaker plugin that would try a range of changes in order of preference to fit everything on a page.  That was for the end-page, only...  It could be extended to go one page at a time, I suppose (if I had saved the code!!!).  AFIK, there have been layout programs in the past (perhaps Quark???) that do these types of try-by-rule processes.  In fact, Quark probably does offer something you can do.  But again, that's pouring your DITA into a DTP system and using what it has to offer.

We have since abandoned FrameMaker as our PDF engine.  We're a tiny team producing lots of doc.  We need the push-button output that DITA is able to deliver.  We switched to oXygen and Chemistry.  That is great, but not even close in the quality of pagination.  CSS is just not rich enough to handle the nuances.  We hard-code attributes in some elements to not break.  But there's no concept of TRY not to break (AFIK). 


conkeyref to <steps> #conref #FrameMaker

Frank Dissinger
 

Hi Bob,


Thank you for your reply. I wasn't aware of this restriction. Seems illogical...


I entered the code you suggested (had to switch to XML View):


<steps conkeyref="key/id">
<step><cmd/></step>
</steps>


but FrameMaker still displays the error message on file save. The conkeyref is resolved, its content displayed, but the content after the conkeyref is discarded.

Error at file xxx.dita.591, line 12, char 133, Message: Expected an element name
Error at line 12, char 183, Message: No character data is allowed by content model
Error at line 12, char 191, Message: Empty content not valid for content model '(stepsection?,step)+'
Parse error at line 12, char 132: Not well-formed (invalid token)
Parsing aborted.

When I switch to XML View, I see the FrameMaker has replaced the dita code with the following:

<steps conkeyref = "key/id"><((stepsection)?,(step))></((stepsection)?,(step))></steps>

Has anyone found out what I have to do to make FrameMaker accept the code?


Thank you also to Lief, but FrameMaker does not even accept that code. It seems that a <cmd> element is also required.


Regards,

Frank




Am 25.11.2019 um 16:10 schrieb Bob Thomas:
Hi Frank,

The content model for <steps> requires at least one <step>, and the content model for <step> requires at least one <cmd>. This true even when using @conref or @conkeyref. Try this:

<steps conkeyref="MyStepsKey">
<step><cmd/></step>
</steps>

The problem that you are having is exactly why I don't like the fact that the DITA content models require elements. This sort of restriction belongs in a Schematron that can be set up to not throw errors when @conref or @conkeyref are used.
--
Best regards,
Bob Thomas
Tagsmiths, LLC

Frank Dissinger

Documentation Manager

....................................................................

CGS Publishing Technologies International GmbH

Email frank.dissinger@... | Web www.cgs-oris.com

Address Kettelerstr. 24 | D-63512 Hainburg | Germany

Phone +49 6182 9626-27 | Fax +49 6182 9626-99

Commercial register Offenbach, HRB no. 21495

Managing directors Bernd Rückert, Andreas Kämmerer, Christoph Thommessen


Re: Page and Column breaks #PDF

ekimber@contrext.com
 

Using either FOP or Antenna House Formatter it is technically possible to implement a multi-pass process using the "area tree" XML that both processors can emit (they are similar but not the same but the programming principles are the same for both).

Using this kind of approach it would be possible to provide a much higher degree of layout awareness to the page composition, for example, detecting the case where a title and paragraph followed by a figure occurs at the bottom of a page. Likewise, it is possible to dynamically size figures and tables based on the layout details of the page.

The main challenge is that the logic to apply will be specific to a given page layout and design coupled with specific content, so it's difficult to have a generic processor, although one could imagine having some set of layout hints that could be embedded in content or applied via style that would then guide a multi-pass pagination process.

For typical full-page layouts the keep facilities in XSL-FO and CSS pagination are sufficient, but when you get into more-constrained layouts, like typical consumer product manuals, it's much harder for a simple keep-with-next or keep-together to produce the correct result.

I've done enough work to date using XSLT to post-process AHF's area tree to know that it would be possible, if even not that difficult, but of course it's not something I personally can do nights and weekends (especially since I seem to have fewer of those available for programming than I used to....)

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 11/25/19, 9:16 AM, "John Piechowski" <dita-users@groups.io on behalf of john@piechowski.org> wrote:

I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could insert a page/column break to force the section header or headline that renders on the bottom of one page to the next page with it's content. Or sometimes there are one or two lines of text left at the bottom on a column that they prefer are with the content on the next column.

Sometimes it is a headline and short paragraph that stays on one page with the image that it references on the next page, making the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly what they wanted using DTP. Now as we promote content reuse, we lost this control without negatively impacting other documents that use the same topic.

We've tried to explain the great benefits we are getting through content reuse: consistency, reduces translation, improved quality. But often, DITA is seen outside the team as a step back in quality.

I'm interested in what others are doing to balance the positive outcome of content reuse against the negative effect document layout.


Re: Page and Column breaks #PDF

Chris Papademetrious
 

Hi John,

We specialized the @base attribute into a @paginate attribute. Using my specialization utility, I used the following code:

 <attributedomain filename="paginateAttMod.rng" domain="paginate">
  <specialize attribute="paginate" from="base" model="(keep-with-next|keep-with-previous|top-of-page|keep-together)*"/>
 </attributedomain>

The attribute allows any number of the highlighted keywords. Oxygen XML Author is smart enough to understand the RelaxNG schema and present the choices to the user in a drop-down box. We use PDF Chemistry for publishing, and we apply this attribute as follows:

@media print {
  *[paginate~="keep-together"] { page-break-inside: avoid; display: block;}
  *[paginate~="keep-with-next"] { page-break-after: avoid; }
  *[paginate~="keep-with-previous"] { page-break-before: avoid; }
  *[paginate~="top-of-page"] { page-break-before: always; }
}

We also added an alternate CSS file to our extension of Oxygen's DITA framework so that writers can toggle visualization of the pagination properties:

/* implement visual markers for pagination properties */
*[paginate ~= "top-of-page"]::before(1000) {
        display: block;
    content: '\00a0';
    height:5px;
    border-top:5px dashed #f00;
    margin-left: -1000in;
    margin-right: -1000in;
}
*[paginate ~= "keep-with-previous"] {
    border-top:5px dotted #0f0 !important;
}
*[paginate ~= "keep-with-next"] {
    border-bottom:5px dotted #0f0 !important;
}
*[paginate ~= "keep-together"] {
    background-color: #cfc !important;
}

This was all we needed to recreate the FrameMaker-like pagination controls in our DITA environment.

 There's more information, including pictures, here:

https://www.oxygenxml.com/forum/post54939.html#p54939

 - Chris


Page and Column breaks #PDF

John Piechowski
 

I'm guessing many of us using DITA receive similar feedback from reviewers that they don't like how text flows in documents.

Often, they relate back to when we were using DTP, and we could insert a page/column break to force the section header or headline that renders on the bottom of one page to the next page with it's content. Or sometimes there are one or two lines of text left at the bottom on a column that they prefer are with the content on the next column.

Sometimes it is a headline and short paragraph that stays on one page with the image that it references on the next page, making the two disconnected.

For many years, it was easy (maybe too easy) to give them exactly what they wanted using DTP. Now as we promote content reuse, we lost this control without negatively impacting other documents that use the same topic.

We've tried to explain the great benefits we are getting through content reuse: consistency, reduces translation, improved quality. But often, DITA is seen outside the team as a step back in quality.

I'm interested in what others are doing to balance the positive outcome of content reuse against the negative effect document layout.

1401 - 1420 of 46276