One of my clients plans to write a new documentation in AsciiDoc, a markup language similar to Markdown or Wikitext, but a bit more versatile. Studio 2017 has no native support so far. Does anyone have some experience with translating AsciiDoc files? Is there a nice workflow already?
I don't want to translate the HTML output.
Thank you in advance!
Paul Filkin | RWS Group
________________________
Design your own training!
You've done the courses and still need to go a little further, or still not clear?
Tell us what you need in our Community Solutions Hub
I can paste here a sample adoc with most common markup formatting syntax:
Translate
= Document Title Template
:revnumber: X.X (DRAFT/APPROVED)
:revdate: Month Date, Year
:keywords: words, related, to, the, document, helping, search
:source-highlighter: highlightjs
:toc: macro
:toclevels: 5
:sectanchors: true
:sectnums:
:sectnumlevels: 5
:includedir: ../styles
:experimental:
:title-page:
:productname: ProductName
:productversion: X.X.x
:classification: CONFIDENTIAL
:icons: font
:data-uri:
:imagesdir:
toc::[]
<<<
ifdef::backend-pdf[]
:numbered!:
== Document revision
[options="header"]
|===
| Version | Date | Notes
| 1.0 | Month Year | Initial version
|===
<<<
endif::[]
:numbered:
== Section Title 1 (About this guide)
== Section Title 2
=== Subsection Title X.1
==== Subsection Title X.1.1
===== Subsection Title X.1.1.1
=== Subsection Title X.2
=== Subsection Title X.3
== Tables
.Three columns table with header row and double sized middle column
[cols="25,50,25",options="header"]
|===
|Column 1, Line 1 |Column 2, Line 1|Column 3, Line 1
|Column 1, Line 2 |Column 2, Line 2|Column 3, Line 2
|Column 1, Line 2 |Column 2, Line 3|Column 3, Line 3
|===
.Four columns table with header row
[cols="25,25,25,25",options=header]
|===
|Column 1, Line 1 |Column 2, Line 1|Column 3, Line 1|Column 4, Line 1
|Column 1, Line 2 |Column 2, Line 2|Column 3, Line 2|Column 4, Line 2
|Column 1, Line 2 |Column 2, Line 3|Column 3, Line 3|Column 4, Line 3
|===
== Steps and lists
=== Steps
To write Steps for a process use "1::, 2::, 3::, x::" with "[horizontal]" attribute on top:
[horizontal]
1:: Step 1
2:: Step 2
3:: Step 3
=== Unordered list
* Item
* Item
* Item
==== Unordered list with sublevels
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
=== Ordered list
. Item 1
. Item 2
. Item 3
==== Ordered list with sublevels
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
=== Mixed list:
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
=== Checklist:
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
== Text formatting
=== Fonts
*Bold*
_Italics_
*_Bold Italics_*
`monospace`
=== Colors
To color some text, use the following syntax:
[source,shell]
----
[color-name]#the text you want to color#
----
For example:
[[colorslist]]
* [blue]#this is a blue text#
* [green]#this is a green text with some _italic_#
* [red]#this is a red text with some *bold*#
* [purple]#this is a purple text with *_bold and italic_*#
* [yellow]#this is a yellow text#
* [fuchsia]#and finally some fuchsia text#
You can use any of the following colors:
* white
* silver
* gray
* black
* red
* maroon
* yellow
* olive
* lime
* green
* aqua
* teal
* blue
* navy
* fuchsia
* purple
=== Superscripts and Subscripts
Put ^carets on either^ side of the text to be superscripted, put ~tildes on either side~ of text to be subscripted. For example:
* e^πi^ +1 = 0
* H~2~O
* x^10^
* Some ^supertext^ and ~subtext~
=== Other text formatting attributes
* [yellow-background]#this is a text with yellow highlight#
* [underline]#Underline text#
* [overline]#overline text#
* [line-through]#line-through#
* [big]#bigger font text#
* [small]#small font text#
=== Combining text formatting elements
You can combine many text formatting elements into the same attribute, for example:
* [blue line-through]*bold blue and line-through*.
* [blue yellow-background]#this is a blue text with yellow highlight#
* [big red]#big red#
* [big red]*big red bold*
* [small blue]#small blue#
* [blue line-through]*bold blue and line-through*
* [big]#bigger and ~subscript~ font text#
== Codeblocks
----
Plain codeblock, not used so much
----
[source,shell]
----
Codeblock in a shell.
----
[source,java]
----
Codeblock with java script
----
[source,xml]
----
Codeblock with xml script
----
== Callouts
Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.
[source,shell]
----
Callout in shell codeblock. <1>
----
<1> Some text.
== Images
.Image title caption
image::images/image.png[Floating image title,300]
Image inline image:images/image.png[Image name can be blank,80] with text.
The images should be stored in a folder _images_ on the same level as the adoc file.
== Admonitions
NOTE: Note about something
TIP: Tip for something
IMPORTANT: Important information about something
CAUTION: Caution
WARNING: Warning regarding something
Admonitions can also encapsulate any block content:
[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:
. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
== Internal cross-references
To create a link to a heading, just include the heading title in <<>>.
----
For details, see section <<Appendix>>.
----
It will be automatically resolved as link to the respective section.
To create a link anywhere in the document, just insert pass:c[[[someID]]] where you need to reference to, and pass:c[<<someID,optionaltextshown>>] where you want to place the link. Make sure the ID is unique and does not contain any special characters. The ID is also case-sensitive.
For example, this is a <<colorslist,link>> to the colors list.
== Links
asciidoctor.org - automatic!
https://asciidoctor.org[Asciidoctor]
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
== Include files
You can include content from another file into the current AsciiDoc document using the `include` directive. The included content can be AsciiDoc or it can be any other text format. Where that content is included in the document determines how it will be processed.
An include directive must be placed on a line by itself with the following syntax:
====
include::path[leveloffset=offset,lines=ranges,tag(s)=name(s),indent=depth,opts=optional]
====
The `leveloffset`, `lines`, `tag(s)``, `indent`, and `opts` attributes are optional, making the simplest case look like:
====
include::content.adoc[]
====
Offset Section Levels::
The `leveloffset` attribute can help here by pushing all headings in the included document down by the specified number of levels. This allows you to publish each chapter as a standalone document (complete with a document title), but still be able to include the chapters into a primary document (which has its own document title).
====
= My Book
include::chapter01.adoc[leveloffset=+1]
include::chapter02.adoc[leveloffset=+1]
include::chapter03.adoc[leveloffset=+1]
====
I can paste here a sample adoc with most common markup formatting syntax:
= Document Title Template
:revnumber: X.X (DRAFT/APPROVED)
:revdate: Month Date, Year
:keywords: words, related, to, the, document, helping, search
:source-highlighter: highlightjs
:toc: macro
:toclevels: 5
:sectanchors: true
:sectnums:
:sectnumlevels: 5
:includedir: ../styles
:experimental:
:title-page:
:productname: ProductName
:productversion: X.X.x
:classification: CONFIDENTIAL
:icons: font
:data-uri:
:imagesdir:
toc::[]
<<<
ifdef::backend-pdf[]
:numbered!:
== Document revision
[options="header"]
|===
| Version | Date | Notes
| 1.0 | Month Year | Initial version
|===
<<<
endif::[]
:numbered:
== Section Title 1 (About this guide)
== Section Title 2
=== Subsection Title X.1
==== Subsection Title X.1.1
===== Subsection Title X.1.1.1
=== Subsection Title X.2
=== Subsection Title X.3
== Tables
.Three columns table with header row and double sized middle column
[cols="25,50,25",options="header"]
|===
|Column 1, Line 1 |Column 2, Line 1|Column 3, Line 1
|Column 1, Line 2 |Column 2, Line 2|Column 3, Line 2
|Column 1, Line 2 |Column 2, Line 3|Column 3, Line 3
|===
.Four columns table with header row
[cols="25,25,25,25",options=header]
|===
|Column 1, Line 1 |Column 2, Line 1|Column 3, Line 1|Column 4, Line 1
|Column 1, Line 2 |Column 2, Line 2|Column 3, Line 2|Column 4, Line 2
|Column 1, Line 2 |Column 2, Line 3|Column 3, Line 3|Column 4, Line 3
|===
== Steps and lists
=== Steps
To write Steps for a process use "1::, 2::, 3::, x::" with "[horizontal]" attribute on top:
[horizontal]
1:: Step 1
2:: Step 2
3:: Step 3
=== Unordered list
* Item
* Item
* Item
==== Unordered list with sublevels
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
=== Ordered list
. Item 1
. Item 2
. Item 3
==== Ordered list with sublevels
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
=== Mixed list:
Operating Systems::
Linux:::
. Fedora
* Desktop
. Ubuntu
* Desktop
* Server
BSD:::
. FreeBSD
. NetBSD
Cloud Providers::
PaaS:::
. OpenShift
. CloudBees
IaaS:::
. Amazon EC2
. Rackspace
=== Checklist:
* [*] checked
* [x] also checked
* [ ] not checked
* normal list item
== Text formatting
=== Fonts
*Bold*
_Italics_
*_Bold Italics_*
`monospace`
=== Colors
To color some text, use the following syntax:
[source,shell]
----
[color-name]#the text you want to color#
----
For example:
[[colorslist]]
* [blue]#this is a blue text#
* [green]#this is a green text with some _italic_#
* [red]#this is a red text with some *bold*#
* [purple]#this is a purple text with *_bold and italic_*#
* [yellow]#this is a yellow text#
* [fuchsia]#and finally some fuchsia text#
You can use any of the following colors:
* white
* silver
* gray
* black
* red
* maroon
* yellow
* olive
* lime
* green
* aqua
* teal
* blue
* navy
* fuchsia
* purple
=== Superscripts and Subscripts
Put ^carets on either^ side of the text to be superscripted, put ~tildes on either side~ of text to be subscripted. For example:
* e^πi^ +1 = 0
* H~2~O
* x^10^
* Some ^supertext^ and ~subtext~
=== Other text formatting attributes
* [yellow-background]#this is a text with yellow highlight#
* [underline]#Underline text#
* [overline]#overline text#
* [line-through]#line-through#
* [big]#bigger font text#
* [small]#small font text#
=== Combining text formatting elements
You can combine many text formatting elements into the same attribute, for example:
* [blue line-through]*bold blue and line-through*.
* [blue yellow-background]#this is a blue text with yellow highlight#
* [big red]#big red#
* [big red]*big red bold*
* [small blue]#small blue#
* [blue line-through]*bold blue and line-through*
* [big]#bigger and ~subscript~ font text#
== Codeblocks
----
Plain codeblock, not used so much
----
[source,shell]
----
Codeblock in a shell.
----
[source,java]
----
Codeblock with java script
----
[source,xml]
----
Codeblock with xml script
----
== Callouts
Callout numbers (aka callouts) provide a means to add annotations to lines in a verbatim block.
[source,shell]
----
Callout in shell codeblock. <1>
----
<1> Some text.
== Images
.Image title caption
image::images/image.png[Floating image title,300]
Image inline image:images/image.png[Image name can be blank,80] with text.
The images should be stored in a folder _images_ on the same level as the adoc file.
== Admonitions
NOTE: Note about something
TIP: Tip for something
IMPORTANT: Important information about something
CAUTION: Caution
WARNING: Warning regarding something
Admonitions can also encapsulate any block content:
[IMPORTANT]
.Feeding the Werewolves
====
While werewolves are hardy community members, keep in mind the following dietary concerns:
. They are allergic to cinnamon.
. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
. Celery makes them sad.
====
== Internal cross-references
To create a link to a heading, just include the heading title in <<>>.
----
For details, see section <<Appendix>>.
----
It will be automatically resolved as link to the respective section.
To create a link anywhere in the document, just insert pass:c[[[someID]]] where you need to reference to, and pass:c[<<someID,optionaltextshown>>] where you want to place the link. Make sure the ID is unique and does not contain any special characters. The ID is also case-sensitive.
For example, this is a <<colorslist,link>> to the colors list.
== Links
asciidoctor.org - automatic!
https://asciidoctor.org[Asciidoctor]
https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
== Include files
You can include content from another file into the current AsciiDoc document using the `include` directive. The included content can be AsciiDoc or it can be any other text format. Where that content is included in the document determines how it will be processed.
An include directive must be placed on a line by itself with the following syntax:
====
include::path[leveloffset=offset,lines=ranges,tag(s)=name(s),indent=depth,opts=optional]
====
The `leveloffset`, `lines`, `tag(s)``, `indent`, and `opts` attributes are optional, making the simplest case look like:
====
include::content.adoc[]
====
Offset Section Levels::
The `leveloffset` attribute can help here by pushing all headings in the included document down by the specified number of levels. This allows you to publish each chapter as a standalone document (complete with a document title), but still be able to include the chapters into a primary document (which has its own document title).
====
= My Book
include::chapter01.adoc[leveloffset=+1]
include::chapter02.adoc[leveloffset=+1]
include::chapter03.adoc[leveloffset=+1]
====
and this would be the output in PDF using asciidoctor-pdf (https://rubygems.org/gems/asciidoctor-pdf)
Product_Documentation_Template.zip
and this would be the HTML output
Thank you... I redid your file and attached it as txt so it doesn't take up so much space in the thread.
This reference is also interesting if someone is interested:
https://powerman.name/doc/asciidoc
I'd say that handling this as a textfile with the regex delimited filetype isn't too difficult. But if there was any sort of demand then a proper filetype developed using the API would clearly be more advantageous. I don't really see that demand so we are very unlikely to do this, but any interested developer can.
On this question, that I missed...
- Is it possible to create rules that can apply all AsciiDoc markups?
- Is that exportable / copyable between different users?
- probably based on the sample from Ioannis and the link I provided above
- yes of course. Just create a custom regex delimited filetype based around these rules and you can export this via the UI in Trados Studio for use by others
Paul Filkin | RWS Group
________________________
Design your own training!
You've done the courses and still need to go a little further, or still not clear?
Tell us what you need in our Community Solutions Hub
Hi Paul,
Thank you for your message.
It has been a few years since I posted my last questions.
We actually found a different solution (i.e. other TMS supporting AsciiDoc native format), so that we don't need any workaround any more, but
thank you once again for your reply and information.
Much appreciated.
Would you mind sharing which?
Well, maybe for a knowledgeable person in both Trados and regex, this shouldn't be a difficult task. But it is for me, thus I am raising this here for official support. If this is such an easy task for you, then this is a chance for a quick win 
So should you later on decide to develop native support of AsciiDoc, much like there is for Markdown, let me know, so I can provide you with demo files, and test any solution before releasing it. I am more than willing to help you out in this respect.
AsciiDoc is becoming more and more popular in the technical writing world, and how to translate AsciiDoc files is a question that keeps popping up in the technical writing forums. So there is definitely a growing demand.
I am actually surprised to read from Paul that they "don't really see that demand so we are very unlikely to do this". AsciiDoc is an increasingly common format and other competitor tools such as Memsource have been offering AsciiDoc filters out of the box for quite some time.
It is supported in Trados Studio 2021 now. It took some time, but it works now.
Hi Tobias Punzmann Thanks for the info. I had just checked the RWS support page listing all file types supported by Trados Studio 2021 and AsciiDoc isn't there, but good to know it is supported now.
If it doesn't work, just add "adoc" to the markdown file types.
