Topics

Using Lightweight DITA's HTML5 format? #LwDITA #HTML5


Mica Semrick
 

I've been looking at migrating the docs for one of my favorite photo editing applications from docbook to something else. I had thought that HDITA would be a great fit for this content, but I can't seem to find much on the format, other than the examples in the spec. I can't create an HDITA topic in Oxygen, I can't find a DTD. Forgive my ignorance, but can someone shed some light on this?

Best,
Mica


Kristen James Eberlein
 

Hi, Mica.

Have you looked at the "Lightweight DITA: An Introduction" committee note? See http://docs.oasis-open.org/dita/LwDITA/v1.0/LwDITA-v1.0.html

No Lightweight DITA spec as yet (and maybe not for a LONG time).

oXygen DOES ship with the DTDs for the XDITA topic and map ...
-- 
Best,
Kris

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


Mark Giffin
 

Hi Mica,

Your observation is correct. There are not a lot of details and examples available about the HTML5 format of Lightweight DITA (HDITA), outside of the committee note on it. I'm on the LWDITA subcommittee and there is no DTD or other schema for HDITA. I think that was largely because it was hard to figure out what to use for it. There is no DTD for HTML5 itself, because they have officially cut ties with SGML (which is where DTDs came from).

Oxygen has good support for MDITA and XDITA (some other tools do also), but not much (none?) for HDITA. In my personal experience, most of the interest is in Markdown/MDITA.

HDITA is basically standard HTML5. It does not violate the HTML5 specs. There is a validator for HTML5:

https://about.validator.nu/
https://github.com/validator/validator/wiki/Service-%C2%BB-HTTP-interface

I think that Oxygen now implements this validator but I have not tested it yet. But that doesn't help you validate HDITA.

By the way, there is also no official validation mechanism for the Markdown format of Lightweight DITA (MDITA). Although the Oxygen Markdown editor may help with this, I'm not certain. And there's no official way to validate ordinary non-LWDITA Markdown either (and there are many flavors of it). I believe most people use their static site generator to "validate" their markdown content. But some people are trying on this.

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/

On 2/6/2020 9:37 AM, Mica Semrick wrote:
I've been looking at migrating the docs for one of my favorite photo editing applications from docbook to something else. I had thought that HDITA would be a great fit for this content, but I can't seem to find much on the format, other than the examples in the spec. I can't create an HDITA topic in Oxygen, I can't find a DTD. Forgive my ignorance, but can someone shed some light on this?

Best,
Mica


Mica Semrick
 

Thank you for the replies Kris & Mark. The original request was for the docs to go into markdown, and I'm still considering MDITA for that, however I have reservations that markdown is expressive enough to capture the necessary information for this documentation set. I also worry about the translation pipeline, which for the current docbook workflow uses GNU get text and PO files. I don't want to hang all the translators out to dry, and I haven't seen great tooling around markdown and translation.

I think vanilla dita is too complicated here, as most seem to be authoring in a text editor. Since it is a Free Software project, many will balk at using a proprietary editor.

I'll continue to think about it; meanwhile I'm open to any suggestions.

-m


On February 6, 2020 3:14:36 PM PST, Mark Giffin <mark@...> wrote:
Hi Mica,

Your observation is correct. There are not a lot of details and examples
available about the HTML5 format of Lightweight DITA (HDITA), outside of
the committee note on it. I'm on the LWDITA subcommittee and there is no
DTD or other schema for HDITA. I think that was largely because it was
hard to figure out what to use for it. There is no DTD for HTML5 itself,
because they have officially cut ties with SGML (which is where DTDs
came from).

Oxygen has good support for MDITA and XDITA (some other tools do also),
but not much (none?) for HDITA. In my personal experience, most of the
interest is in Markdown/MDITA.

HDITA is basically standard HTML5. It does not violate the HTML5 specs.
There is a validator for HTML5:

https://about.validator.nu/
https://github.com/validator/validator/wiki/Service-%C2%BB-HTTP-interface

I think that Oxygen now implements this validator but I have not tested
it yet. But that doesn't help you validate HDITA.

By the way, there is also no official validation mechanism for the
Markdown format of Lightweight DITA (MDITA). Although the Oxygen
Markdown editor may help with this, I'm not certain. And there's no
official way to validate ordinary non-LWDITA Markdown either (and there
are many flavors of it). I believe most people use their static site
generator to "validate" their markdown content. But some people are
trying on this.

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/


On 2/6/2020 9:37 AM, Mica Semrick wrote:
I've been looking at migrating the docs for one of my favorite photo
editing applications from docbook to something else. I had thought
that HDITA would be a great fit for this content, but I can't seem to
find much on the format, other than the examples in the spec. I can't
create an HDITA topic in Oxygen, I can't find a DTD. Forgive my
ignorance, but can someone shed some light on this?

Best,
Mica




Groups.io Links: You receive all messages sent to this group.

View/Reply Online (#45175): https://dita-users.groups.io/g/main/message/45175
Mute This Topic: https://groups.io/mt/71028148/2985651
Mute #lwdita: https://groups.io/mk?hashtag=lwdita&subid=5779837
Mute #html5: https://groups.io/mk?hashtag=html5&subid=5779837
Group Owner: main+owner@dita-users.groups.io
Unsubscribe: https://dita-users.groups.io/g/main/leave/defanged [mica@...]


despopoulos_chriss
 

There's no reason that you can't just use a subset of DITA that almost completely resembles HTML.  Just use topic, and pretty much all that needs to be different it topic and title.  Just ignore all the other stuff.  With very little effort you can have people producing this minimal DITA in text editors. 

That's pretty much what we do...  We use conref and maybe a few other things, but we're effectively using a self-imposed LW DITA.  And then we just transform to HTML in the browser. 

Another approach could be to use XHTML, and then for translation set up a transform to DITA...  And back to XHTML again.  You just have to be a bit rigorous about the acceptable structure in your XHTML...  No nesting heading levels too deeply in a single file. 

Just a couple of thoughts...


Jonathan Hanna
 

Hi Mica,

The DITA Open Toolkit also supports Markdown with some extensions:
https://www.dita-ot.org/dev/topics/markdown-dita-syntax-reference.html

If you need something that's more expressive, you can also apply `outputclass` attributes to headers.

Jonathan


Mark Giffin
 

The XML format of Lightweight DITA (XDITA) is pretty much what Chris describes, it is only topic and map with only a few elements compared to full DITA:

https://docs.oasis-open.org/dita/LwDITA/v1.0/cn02/LwDITA-v1.0-cn02.html#what-is-xdita

Mica, you could also mix XDITA and MDITA (markdown) and HDITA in the same map, if some topics required more control than others. This works with the DITA OT right now (except for HDITA, which I'm not sure about).

Mark Giffin
Mark Giffin Consulting, Inc.
http://markgiffin.com/


On 2/7/2020 2:24 AM, despopoulos_chriss via Groups.Io wrote:
There's no reason that you can't just use a subset of DITA that almost completely resembles HTML.  Just use topic, and pretty much all that needs to be different it topic and title.  Just ignore all the other stuff.  With very little effort you can have people producing this minimal DITA in text editors. 

That's pretty much what we do...  We use conref and maybe a few other things, but we're effectively using a self-imposed LW DITA.  And then we just transform to HTML in the browser. 

Another approach could be to use XHTML, and then for translation set up a transform to DITA...  And back to XHTML again.  You just have to be a bit rigorous about the acceptable structure in your XHTML...  No nesting heading levels too deeply in a single file. 

Just a couple of thoughts...