Date   

Re: <resourceid> element's @appid attribute

john.kirkilis@...
 

On Wed, Feb 10, 2021 at 10:01 AM, ekimber@... wrote:
An ID used by an application to identify the topic.
Thanks Elliot for mentioning the DITA 2.0 proposal. I'll check it out.

My question has more to do with the description of the @appid attribute. The @appname is obviously the name of the application that is being documented, such as "OxygenXML"or "Apache Tomcat", and the name "appid" would lead me to believe that it's a way to more specifically identify specific parts of the application identified by @appname, whether it be a page, tab, window, dialog box, form field, etc. However the description, "An ID used by an application to identify the topic" indicates to me that it's an id the application uses to refer to a documentation topic, not a part of the application, and the note which says that @appid should be used instead of the @id attribute in DITA 1.2's use of <resourceid> further makes it sound like its a way to refer to a DITA topic rather than an aspect of the application. In addition, the definition of @ux-context-string, "Contains the value of a user-assistance context-string that is used to identify the topic", confuses me as well by including "identify the topic" instead of ""further identify the context of the application" being documented.

Perhaps, I'm being overly literal, but I would appreciate clarity on which attributes refer to aspects of the documentation and which refer to the application being documented.


AntennaHouse PDF ML

Bill Burns
 

Hello!

Looking at recommending a base for some PDF plugins on a couple of projects. We're curious how many people are using the PDF5 ML plugin from AntennaHouse to base their plugs. It seems well designed and surprisingly nonproprietary given its origin. 

If you have used it as your base, what challenges have you encountered with it? How does it compare favorably to the PDF2 plugin?

Thanks,
--
Bill Burns
512-646-2100
--
We are [A] 


Help with filtering in com.elovirta.ooxml #conditional-processing

Leigh White
 

Hi all,

I'm setting up the com.elovirta.ooxml plugin for a customer. Using with OT 2.5.4. They will be using @audience pretty extensively to both filter some elements, and color-code others. For the latter, I have set up a ditaval that flags content based on the value of @audience. This works exactly as expected for pdf outputs but seems to have no effect whatsoever for ooxml output. My knowledge of this plugin and ooxml in general is pretty slim. I'm wondering if the failure lies in the plugin--that it just doesn't account for flagging, or in the template---that some accommodation would need to be made there for displaying the background color? Looking at the CLEANED file, it appears that the flagging is preserved to that point:

<ditaval-startprop class="+ topic/foreign ditaot-d/ditaval-startprop " outputclass="background-color:yellow;">
<prop xmlns:dita-ot="http://dita-ot.sourceforge.net" action="flag" att="audience" backcolor="yellow" val="optional"/>
</ditaval-startprop>split up as indicated<ditaval-endprop class="+ topic/foreign ditaot-d/ditaval-endprop ">
<prop xmlns:dita-ot="http://dita-ot.sourceforge.net" action="flag" att="audience" backcolor="yellow" val="optional"/>
</ditaval-endprop>

So I'm not sure where it gets lost. Any help appreciated!

Thanks,
Leigh


Re: <resourceid> element's @appid attribute

ekimber@contrext.com
 

The intent of resourceid is to allow you to associate arbitrary, application-specific identifiers, with topics or other resources addressed by topicrefs.

So if by "representation" you mean "how do I tag it up?" I think the answer is: You create a topic with the help content, associate a resource IDs with it, and then include those IDs in the published help for the target system, whatever that means.

I think the implication here is that individual fields will need to be documented in individual topics, as opposed to within the body of a topic (i.e., in a table, definition list, using section elements, whatever).

There's no defined mechanism using <resourceid> to bind a resource ID to an element within a topic, which is what I think you're asking for. I could see a given help system providing some convention for that, i.e., combining the topic's resource ID with an element ID from within the topic to create a resolvable anchor in the published help, but that behavior would be beyond what the DITA standard defines.

DITA's naming and addressing architecture basically says "the unit of addressability exposed to the outside world is the topicref". This is implicit (or, arguably, explicit) in the fact that maps are the place where you can define globally-unique identifiers for things by using keys or resource IDs to bind names to the things the topicrefs reference in the context of a specific root map.

Because root maps have identity (they are objects in the general computer science sense of things that have identity within the set of all possible things), by definition, the names defined in them are globally unique (because the location of the root map establishes a unique base address for all the unique names defined in the map). In particular, keys are, by definition, unique within the scope of a given root map. In terms of Web architecture, every root map has a unique URI and thus establishes a unique base URI for all the names defined within that root map, making all the names globally unique among all URI-addressible resources. (This is true for XML documents generally but in DITA root maps have a special role in that root maps cannot themselves be re-used. That's what being "root" means: a map that is not re-used directly by any other map.) The implication is that, because root maps have global identity (unique URIs), deliverables produced from them also have global identity, so the uniqueness of identifiers in root maps carry over to the deliverables produced from those root maps (or, more precisely, can be carried over to the deliverables produced from those root maps, since deliverable production systems can do whatever they way, including breaking the inherent uniqueness of the identifiers in the DITA source--the most the DITA standard can do is define the required properties of the source content).

Resource IDs are not, by the rules of the DITA spec, globally unique because there's no rule that prevents you assigning the same application name/app-id pair to multiple topics or topcirefs in the context of a single root map, but you would normally want to do that in order for your published help system to work correctly. This allows you to keep the DITA-specific identifiers (keys) separate from any application-specific identifiers you need to publish to. It also allows adding new application-specific identifiers after the fact (to avoid, for example, having to modify existing keys or adding additional keys, which could be disruptive or difficult depending on how you are using or not using keys).

Note that for DITA 2.0 we have just accepted a proposal to extend <resourceid> to allow it to satisfy the requirements for which @copy-to is currently used.

This proposal doesn't change anything about the DITA 1.3 definition of <resourceid> but does extend it to play a more general role in defining deliverable-specific anchor information, something that @copy-to was designed to do but that it didn't really do very well. So for example, if you have the requirement to define, on a topicref, that the referenced topic should have a specific HTML filename in the published HTML rendering of that topic, <resourceid> in DITA 2.0 will allow you to say that more explicitly than you can today (although you can use <resourceid> for that today given appropriate support in your publishing tools and some tools in fact do that today, using <resourceid> app-ids to generate anchors in HTML).

The main thing we add to <resourceid> is a way for authors to indicate that a given <resourceid> element is providing deliverable anchor information instead of help system identifiers (the original intended use and what existing systems that use <resourceid> assume when there is no @appname value). We also refine and clarify how <resourceid> information should be used by processors in the construction of deliverable anchors (tl;dr: processors should use the <resourceid> information as much as possible in a clear and consistent way so that the deliverable anchors produced for a given deliverable are as predictable and repeatable as possible, understanding that the details of deliverable generation, including anchor construction, are necessarily processor dependent).

Cheers,

E.

--
Eliot Kimber
http://contrext.com


On 2/9/21, 7:07 PM, "main@dita-users.groups.io on behalf of john.kirkilis@nokia.com" <main@dita-users.groups.io on behalf of john.kirkilis@nokia.com> wrote:

The DITA 1.3 spec describes the @appid attribute of the <resourceid> as follows:

An ID used by an application to identify the topic.

While the @ux-context-string is defined as:

Contains the value of a user-assistance context-string that is used to identify the topic.

What I'm not clear about is how a UX resource, whether it be a page of a webapp or an individual field in a webform, should be represented in DITA so that when a help icon is clicked on a UX widget in a webapp, the proper topic can be referenced.


Re: <resourceid> element's @appid attribute

Radu Coravu
 

Hi John,

Not sure if this answers your question but for example in the Oxygen WebHelp Responsive output we use the "resourceid" to gather such application IDs and redirect to the topics containing them when the application ID is given in a query string to the web help output:

https://www.oxygenxml.com/doc/versions/23.0/ug-editor/topics/whr-context-sensitive.html

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 2/10/21 03:07, john.kirkilis@... wrote:

The DITA 1.3 spec describes the @appid attribute of the <resourceid> as follows:
An ID used by an application to identify the topic.
While the @ux-context-string is defined as:
Contains the value of a user-assistance context-string that is used to identify the topic.
What I'm not clear about is how a UX resource, whether it be a page of a webapp or an individual field in a webform, should be represented in DITA so that when a help icon is clicked on a UX widget in a webapp, the proper topic can be referenced.

  


<resourceid> element's @appid attribute

john.kirkilis@...
 

The DITA 1.3 spec describes the @appid attribute of the <resourceid> as follows:
An ID used by an application to identify the topic.
While the @ux-context-string is defined as:
Contains the value of a user-assistance context-string that is used to identify the topic.
What I'm not clear about is how a UX resource, whether it be a page of a webapp or an individual field in a webform, should be represented in DITA so that when a help icon is clicked on a UX widget in a webapp, the proper topic can be referenced.


[ann][webinar] Transforming XML and HTML documents to PDF using CSS, Part 2 – Lists, Tables and Images #Oxygen

alin_belu@...
 

Hello, 
 
In the first part of the “Transforming XML and HTML documents to PDF using CSS” tutorial series, we aimed to teach you a basic understanding of the CSS layout to help you customize your PDF output. Now, you are ready to continue your journey into defining the look and format of your documents! 
 
Tomorrow (February 10), we bring you the second installment titled “Lists, Tables and Images” where Julien Lacour (software developer at Syncro Soft) will teach you more advanced CSS properties that will help you to: 
* Customize unordered and ordered lists, list-items, list bullets, etc. 
* Set table elements such as headers / footers / captions / size. 
* Display images by defining size, resolution, remote images, etc. 
* Select a particular node or set of nodes from the document with CSS combinators. 
* Create more complex elements with the ::before and ::after pseudo-elements. 
 
This is a free event and you can register at http://www.oxygenxml.com/evs2021-4.html 
 
Make sure to check the full list of our upcoming events: https://www.oxygenxml.com/events_programme.html 
 
Best regards,
Alin
--
Alin Belu
Oxygen XML Editor


Re: keep with

Chris Papademetrious
 

Hi Aaron,

If you are using the HTML5/CSS PDF transformation in Oxygen, it's pretty easy. Here is how we give authors manual control over pagination:

Making pagination controls accessible to DITA writers

You don't need to create a separate attribute for this (outputclass works fine), but I felt that doing so made it a bit more writer-friendly.

And we also do some automatic pagination handling for the writers. For example, we keep <p> introductions ending in ":" or "," with the following content, but you could easily extend this to images following procedure steps and so on (which is a good idea, actually!). Here's how we do that:

Automatically keeping introduction paragraphs with their content

We even have a Schematron check (mentioned in the preceding link's discussion) that tells writers when they've used a manual @paginate attribute in a scenario where it's automatically applied, which helps them dynamically learn the contexts in which it will be handled for them.


Hi Chris,

We use this setting to keep table rows from being split across pages:

@media print {
  *[class~='topic/row'] { page-break-inside: avoid; }
}

I put it in @media print to be pedantically correct.  :)


Re: keep with

despopoulos_chriss
 

Hi Radu...  Since we have your attention on this...  With CSS to PDF, can you avoid page breaks in a table row, but still allow the table itself to span pages?

Thanks                 cud


Re: keep with

Radu Coravu
 

Hi,

There are various properties in the CSS which control the page breaks if you are using CSS to produce PDF:

https://www.oxygenxml.com/doc/versions/23.0/ug-editor/topics/dcpp_page_breaking.html#dcpp_how_to_avoid_page_breaks_in_lists_and_tables

and combined with that Nick said, with the possibility to use a custom outputclass attribute either on the image or on its parent step you may be able to achieve what you want.

Regards,

Radu

On 2/7/21 18:15, Nicholas Mucks via groups.io wrote:
Hi Aaron,
You’ll probably want an outputclass. We do something similar with tables in PDF. The outputclass will also become a class attribute value in the CSS if you’re relying on the HTML5 plugin as your base for customizations.

For example, if a writer sets outputclass=keep-together on their table then we add keep-together.within-page to the table in the XSL-FO attributes. (It’s just a choose statement in the attribute declaration.) This then forces the table to render within one PDF page.


Take care,
- Nick

Sent from mobile

On Feb 6, 2021, at 9:58 PM, Aaron Mehl via groups.io <mehlzaidy770@...> wrote:


Hi all,
Is there a way within Dita to force an image to stay with the previous or next steps in a task?
I googled and saw ways to do this with xslt, but I was wondering if there is an attribute within Dita, or can I achieve the same thing with css.
I am using Oxygen.
Thanks,
Aaron
-- 
Radu Coravu
Oxygen XML Editor


Re: keep with

Nicholas Mucks
 

Hi Aaron,
You’ll probably want an outputclass. We do something similar with tables in PDF. The outputclass will also become a class attribute value in the CSS if you’re relying on the HTML5 plugin as your base for customizations.

For example, if a writer sets outputclass=keep-together on their table then we add keep-together.within-page to the table in the XSL-FO attributes. (It’s just a choose statement in the attribute declaration.) This then forces the table to render within one PDF page.


Take care,
- Nick

Sent from mobile

On Feb 6, 2021, at 9:58 PM, Aaron Mehl via groups.io <mehlzaidy770@...> wrote:


Hi all,
Is there a way within Dita to force an image to stay with the previous or next steps in a task?
I googled and saw ways to do this with xslt, but I was wondering if there is an attribute within Dita, or can I achieve the same thing with css.
I am using Oxygen.
Thanks,
Aaron


keep with

Aaron Mehl
 

Hi all,
Is there a way within Dita to force an image to stay with the previous or next steps in a task?
I googled and saw ways to do this with xslt, but I was wondering if there is an attribute within Dita, or can I achieve the same thing with css.
I am using Oxygen.
Thanks,
Aaron


Re: Custom dita-ot plugins directory in configuration.properties #DITA-OT

Radu Coravu
 

Hi Nicolas,

So in the Oxygen Preferences->DITA page you set the DITA OT engine to point to your custom DITA OT folder, right?

Not sure what the problem is, if you want further help maybe you can contact us directly (support@...) and give us some steps to reproduce the problem on our side.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 2/2/21 10:06, Nicolas Delobel wrote:

Hi Radu,

I made a test with oXygen 23 but unfortunately I still have an error message:

Buildfile: C:\myproject\dita-ot-3.6-oxy23\build.xml

BUILD FAILED
C:\myproject\dita-ot-3.6-oxy23\build.xml:19: The following error occurred while executing this line:
C:\myproject\dita-ot-3.6-oxy23\plugins\org.dita.base\build.xml:36: The following error occurred while executing this line:
C:\myproject\dita-ot-3.6-oxy23\plugins\org.dita.base\build_init.xml:23: taskdef class org.dita.dost.ant.InitializeProjectTask cannot be found
 using the classloader AntClassLoader[]

Total time: 0 seconds

The process finished with exit code: 1

Regards,
Nicolas

  


Re: Any one using Oxygen as an editor with an AEM XML Documentation solution?

Julio J Vazquez
 

Sure, Kris, we can talk. I'm not sure how helpful I would be, but I think the discussion would be beneficial. I think you still have my personal email, so send me some proposed times. 

Julio J. Vazquez


Re: Any one using Oxygen as an editor with an AEM XML Documentation solution?

John Piechowski
 

Kristen,

I tried to use Oxygen and the connector implementation is buggy and clunky. It doesn't always lock/unlock as you would expect and if you try to check out an entire map to edit the whole book, it doesn't always download all the assets. Ultimately, we decided to stay in the AEM Editor. With the latest update it's a pretty good experience, although I understand what you're saying about <alt> - maybe you could get Adobe to get <alt> into the product...

John

On Tue, Feb 2, 2021 at 7:19 AM Kristen James Eberlein <kris@...> wrote:

Hi, Julio. Are you up for having a brief conversation about this? I'm concerned about the user experience for NON-POWER USERS. As far as I can tell, using Oxygen though WebDAV bypasses a lot of AEM version control. It gives a solid Oxygen authoring experience -- and I can see that authors can lock and unlock objects -- but if authors move objects around there will be a lot of broken references.

Your thoughts? And those of any others with input.

The only reason I am considering Oxygen XML Editor is that the built-in AEM Web editor does not display the <alt> element. I don't want to force content authors to enter the code view in order to add alternate text for an image.

Yes, the AEM built-in Web editor enables content authors to add alternate text for images using the @alt attribute, but the @alt attribute has been deprecated since 2010 and is removed in DITA 2.0. I TRULY HATE to encourage a brand-new DITA implementation to use a deprecated feature ...

Best,
Kris

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


On 2/2/2021 6:47 AM, Julio J Vazquez via groups.io wrote:
Hi Kristen,

I'm raising my hand. 

Julio J. Vazquez


Re: Any one using Oxygen as an editor with an AEM XML Documentation solution?

Kristen James Eberlein
 

Hi, Julio. Are you up for having a brief conversation about this? I'm concerned about the user experience for NON-POWER USERS. As far as I can tell, using Oxygen though WebDAV bypasses a lot of AEM version control. It gives a solid Oxygen authoring experience -- and I can see that authors can lock and unlock objects -- but if authors move objects around there will be a lot of broken references.

Your thoughts? And those of any others with input.

The only reason I am considering Oxygen XML Editor is that the built-in AEM Web editor does not display the <alt> element. I don't want to force content authors to enter the code view in order to add alternate text for an image.

Yes, the AEM built-in Web editor enables content authors to add alternate text for images using the @alt attribute, but the @alt attribute has been deprecated since 2010 and is removed in DITA 2.0. I TRULY HATE to encourage a brand-new DITA implementation to use a deprecated feature ...

Best,
Kris

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


On 2/2/2021 6:47 AM, Julio J Vazquez via groups.io wrote:
Hi Kristen,

I'm raising my hand. 

Julio J. Vazquez


Re: Any one using Oxygen as an editor with an AEM XML Documentation solution?

Julio J Vazquez
 

Hi Kristen,

I'm raising my hand. 

Julio J. Vazquez


Re: Custom dita-ot plugins directory in configuration.properties #DITA-OT

Nicolas Delobel
 

Hi Radu,

I made a test with oXygen 23 but unfortunately I still have an error message:

Buildfile: C:\myproject\dita-ot-3.6-oxy23\build.xml

BUILD FAILED
C:\myproject\dita-ot-3.6-oxy23\build.xml:19: The following error occurred while executing this line:
C:\myproject\dita-ot-3.6-oxy23\plugins\org.dita.base\build.xml:36: The following error occurred while executing this line:
C:\myproject\dita-ot-3.6-oxy23\plugins\org.dita.base\build_init.xml:23: taskdef class org.dita.dost.ant.InitializeProjectTask cannot be found
 using the classloader AntClassLoader[]

Total time: 0 seconds

The process finished with exit code: 1

Regards,
Nicolas


Re: Custom dita-ot plugins directory in configuration.properties #DITA-OT

Radu Coravu
 

Hi Nicolas,

I agree the problem was in Oxygen not properly detecting libraries in external DITA OT plugins folders.

If you get a chance to test the fix in Oxygen 23 please tell us if it works better or not.

Regards,

Radu

Radu Coravu
Oxygen XML Editor
On 2/1/21 14:48, Nicolas Delobel wrote:

Thanks Pierre,

Indeed, it's linked to Oxygen (see topic about this issue on oXygen forum: https://www.oxygenxml.com/forum/post60146.html?hilit=configuration.properties#p60146)
It seems to be corrected on Oxygen 23. I didn't test yet.

When I run the transformation outside of oXygen with dita-ot command line, it works.

Nicolas

  


Re: Any one using Oxygen as an editor with an AEM XML Documentation solution?

Tonia
 

We are, sorta. There is no integration between the two. We only download manually and work in Oxygen when we have a gnarly topic or a lot of work to do quickly.

On Feb 1, 2021, at 2:44 PM, Kristen James Eberlein <kris@eberleinconsulting.com> wrote:

Let me know, please. Thanks!

Best,
Kris

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







281 - 300 of 46276