Highlighted

Trying Structured: Conversion Table Questions

Contributor ,
Dec 08, 2015

Copy link to clipboard

Copied

So, finally I am going to give structured FM a serious whirl. My unstructured FM style use is consistent and predictable.

I am trying to use online resources, including, http://help.adobe.com/en_US/FrameMaker/12.0/Help/Using/index.html, I saw Adobe's samples from File > New > Document > Explore Structured Templates, but, honestly, they are light. Also, I watched the one Adobe TV video on converting from unstructured to structured.. However, I am missing some information.


I am working on my first conversion table:

1) What element name conventions should I follow? I am using Pascal case right now, but don't mind using all lowercase if it's preferred. What names should I use? "P" for body text or "Para," for example?

2) I understand to map Heading styles to elements I call "Head," and various Body styles to elements I name "Para." My bullets and numbered lists I map to elements I call, "Item," and I plan to create a "List" wrapper for these, for example. Item is set with an attribute of "Type" that can be "Numbered" or "Bulleted." I know there are other ways to approach that, such as using explicit UL and OL elements or wrappers.

3) What do I do with the paragraphs I anchor graphics to? I have an AnchorGraphics tag for anchoring images and an AnchorTable tag for anchoring tables. Should these become "Para"? Should and can I map a FrameMaker tag to no element, so it goes away?

4) What should I do with notes, cautions, and warnings? Are these also best as "Para" elements, or should they get their own?


Do you have thoughts and other resources?


Thanks!

Sean,

I think you may be asking questions with no solid answers. There are likely a sizable variety of opinions out there, all of which are just that... opinions. The short answer is that you have to figure out what works for you, and this may not be what works for someone else.

There are some that would tell you to forget this whole exercise and just use an existing data structure, like DITA or Docbook. This is certainly an option. I do not use either because neither works for me.

So, let me tell you what does work for me, in reference to the questions you asked. This is all subjective in your case, but it is based on a well-used and highly-refined workflow, producing good results for many years.

1 - Element name conventions - I like the lower-case element names that DITA uses, like <p>, <fig>, <ol>, etc. because 1) They are short and easy to visualize  2) I know what they mean because I'm an author and they also look like HTML in some cases 3) The shorter the element tag, the less overhead in the structured file and also XML, if you export to XML.

2 - As an author, I find it much quicker to specify an explicit <ol> or <ul> element, rather than set an attribute. Furthermore, it is much easier to visualize in the structure view. Furthermore, it is less overhead in the source file. DITA calls a heading element <title>... I like that better than <Head>, but again, that's just me.

3 - For figures, I use a <fig> element which maps to my "AnchorGraphics" tag. The <fig> element has two children... <image> and <title>. The <image> element is a graphic element that inserts an anchored frame into the empty AnchorGraphics paragraph (created by <fig>). Then, the container <title> element inserts a new paragraph for the figure caption. The end result is the same as standard unstructured FM usage, except that the management of the AnchorGraphics placeholder is much better automated and controlled. IOW, you don't have to worry about it anymore... the element structure does it for you. One of the myriad of benefits of structure.

4 - DITA defines a single <note> element which has an attribute to control whether it appears as a note, caution, etc. I like this approach. You could reuse the <para> element but my thought is that this would really complicate your formatting context rules. The explicit <note> element seems much better.

5 - Tables - Yes to your basic question, although there are plenty of different names you could choose for the elements. To comply with the CALS or DITA model, you would also need one more ancestor in the tree that is the parent to the actual table element. In DITA, this is the <table> element, and the actual table element is a <tgroup> element as a child. In my EDD, the <table> element works very much like the <fig> element, inserting an empty paragraph into which the child <tgroup> element inserts the actual table. This models typical unstructured usage and works very well for me.

Throughout all of this, you'll note that I reference DITA a lot, but claim that I don't use DITA. I really like the DITA structure definition (the <topic> DTD mainly)... I find it very intuitive and well-designed for general authoring. However, I find little use for other DITA things, like its focus on topic-oriented content management and a huge swath of other complexities that are just a nuisance if you don't need them. So, I effectively have my own EDD, but the underlying structure definition is mostly ripped off from DITA. I'd encourage you to at least look at the DITA spec and see how they did it. The simplest way would be to use the FM menus to create a sample DITA topic and mess around with it.

I hope this helps.

Russ

TOPICS
Structured

Views

341

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more

Trying Structured: Conversion Table Questions

Contributor ,
Dec 08, 2015

Copy link to clipboard

Copied

So, finally I am going to give structured FM a serious whirl. My unstructured FM style use is consistent and predictable.

I am trying to use online resources, including, http://help.adobe.com/en_US/FrameMaker/12.0/Help/Using/index.html, I saw Adobe's samples from File > New > Document > Explore Structured Templates, but, honestly, they are light. Also, I watched the one Adobe TV video on converting from unstructured to structured.. However, I am missing some information.


I am working on my first conversion table:

1) What element name conventions should I follow? I am using Pascal case right now, but don't mind using all lowercase if it's preferred. What names should I use? "P" for body text or "Para," for example?

2) I understand to map Heading styles to elements I call "Head," and various Body styles to elements I name "Para." My bullets and numbered lists I map to elements I call, "Item," and I plan to create a "List" wrapper for these, for example. Item is set with an attribute of "Type" that can be "Numbered" or "Bulleted." I know there are other ways to approach that, such as using explicit UL and OL elements or wrappers.

3) What do I do with the paragraphs I anchor graphics to? I have an AnchorGraphics tag for anchoring images and an AnchorTable tag for anchoring tables. Should these become "Para"? Should and can I map a FrameMaker tag to no element, so it goes away?

4) What should I do with notes, cautions, and warnings? Are these also best as "Para" elements, or should they get their own?


Do you have thoughts and other resources?


Thanks!

Sean,

I think you may be asking questions with no solid answers. There are likely a sizable variety of opinions out there, all of which are just that... opinions. The short answer is that you have to figure out what works for you, and this may not be what works for someone else.

There are some that would tell you to forget this whole exercise and just use an existing data structure, like DITA or Docbook. This is certainly an option. I do not use either because neither works for me.

So, let me tell you what does work for me, in reference to the questions you asked. This is all subjective in your case, but it is based on a well-used and highly-refined workflow, producing good results for many years.

1 - Element name conventions - I like the lower-case element names that DITA uses, like <p>, <fig>, <ol>, etc. because 1) They are short and easy to visualize  2) I know what they mean because I'm an author and they also look like HTML in some cases 3) The shorter the element tag, the less overhead in the structured file and also XML, if you export to XML.

2 - As an author, I find it much quicker to specify an explicit <ol> or <ul> element, rather than set an attribute. Furthermore, it is much easier to visualize in the structure view. Furthermore, it is less overhead in the source file. DITA calls a heading element <title>... I like that better than <Head>, but again, that's just me.

3 - For figures, I use a <fig> element which maps to my "AnchorGraphics" tag. The <fig> element has two children... <image> and <title>. The <image> element is a graphic element that inserts an anchored frame into the empty AnchorGraphics paragraph (created by <fig>). Then, the container <title> element inserts a new paragraph for the figure caption. The end result is the same as standard unstructured FM usage, except that the management of the AnchorGraphics placeholder is much better automated and controlled. IOW, you don't have to worry about it anymore... the element structure does it for you. One of the myriad of benefits of structure.

4 - DITA defines a single <note> element which has an attribute to control whether it appears as a note, caution, etc. I like this approach. You could reuse the <para> element but my thought is that this would really complicate your formatting context rules. The explicit <note> element seems much better.

5 - Tables - Yes to your basic question, although there are plenty of different names you could choose for the elements. To comply with the CALS or DITA model, you would also need one more ancestor in the tree that is the parent to the actual table element. In DITA, this is the <table> element, and the actual table element is a <tgroup> element as a child. In my EDD, the <table> element works very much like the <fig> element, inserting an empty paragraph into which the child <tgroup> element inserts the actual table. This models typical unstructured usage and works very well for me.

Throughout all of this, you'll note that I reference DITA a lot, but claim that I don't use DITA. I really like the DITA structure definition (the <topic> DTD mainly)... I find it very intuitive and well-designed for general authoring. However, I find little use for other DITA things, like its focus on topic-oriented content management and a huge swath of other complexities that are just a nuisance if you don't need them. So, I effectively have my own EDD, but the underlying structure definition is mostly ripped off from DITA. I'd encourage you to at least look at the DITA spec and see how they did it. The simplest way would be to use the FM menus to create a sample DITA topic and mess around with it.

I hope this helps.

Russ

TOPICS
Structured

Views

342

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Dec 08, 2015 0
Contributor ,
Dec 08, 2015

Copy link to clipboard

Copied

What to do with tables is another issue.

Do I make the text, "Para" elements. Then, wrap these in "Cell" wrappers, those in "Row" wrappers, and rows in ""TBody" and "THead" wrapper depending where in the table the row is?

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Dec 08, 2015 0
Mentor ,
Dec 09, 2015

Copy link to clipboard

Copied

Sean,

I think you may be asking questions with no solid answers. There are likely a sizable variety of opinions out there, all of which are just that... opinions. The short answer is that you have to figure out what works for you, and this may not be what works for someone else.

There are some that would tell you to forget this whole exercise and just use an existing data structure, like DITA or Docbook. This is certainly an option. I do not use either because neither works for me.

So, let me tell you what does work for me, in reference to the questions you asked. This is all subjective in your case, but it is based on a well-used and highly-refined workflow, producing good results for many years.

1 - Element name conventions - I like the lower-case element names that DITA uses, like <p>, <fig>, <ol>, etc. because 1) They are short and easy to visualize  2) I know what they mean because I'm an author and they also look like HTML in some cases 3) The shorter the element tag, the less overhead in the structured file and also XML, if you export to XML.

2 - As an author, I find it much quicker to specify an explicit <ol> or <ul> element, rather than set an attribute. Furthermore, it is much easier to visualize in the structure view. Furthermore, it is less overhead in the source file. DITA calls a heading element <title>... I like that better than <Head>, but again, that's just me.

3 - For figures, I use a <fig> element which maps to my "AnchorGraphics" tag. The <fig> element has two children... <image> and <title>. The <image> element is a graphic element that inserts an anchored frame into the empty AnchorGraphics paragraph (created by <fig>). Then, the container <title> element inserts a new paragraph for the figure caption. The end result is the same as standard unstructured FM usage, except that the management of the AnchorGraphics placeholder is much better automated and controlled. IOW, you don't have to worry about it anymore... the element structure does it for you. One of the myriad of benefits of structure.

4 - DITA defines a single <note> element which has an attribute to control whether it appears as a note, caution, etc. I like this approach. You could reuse the <para> element but my thought is that this would really complicate your formatting context rules. The explicit <note> element seems much better.

5 - Tables - Yes to your basic question, although there are plenty of different names you could choose for the elements. To comply with the CALS or DITA model, you would also need one more ancestor in the tree that is the parent to the actual table element. In DITA, this is the <table> element, and the actual table element is a <tgroup> element as a child. In my EDD, the <table> element works very much like the <fig> element, inserting an empty paragraph into which the child <tgroup> element inserts the actual table. This models typical unstructured usage and works very well for me.

Throughout all of this, you'll note that I reference DITA a lot, but claim that I don't use DITA. I really like the DITA structure definition (the <topic> DTD mainly)... I find it very intuitive and well-designed for general authoring. However, I find little use for other DITA things, like its focus on topic-oriented content management and a huge swath of other complexities that are just a nuisance if you don't need them. So, I effectively have my own EDD, but the underlying structure definition is mostly ripped off from DITA. I'd encourage you to at least look at the DITA spec and see how they did it. The simplest way would be to use the FM menus to create a sample DITA topic and mess around with it.

I hope this helps.

Russ

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Dec 09, 2015 1
Contributor ,
Dec 10, 2015

Copy link to clipboard

Copied

What a terrific answer!

As a follow-up, do you have any resources to suggest? I am using several, but will take all I can get, and haven't tried DITA, so, FM unstructured to DITA would be helpful.

Cheers,

Sean

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Dec 10, 2015 0
Mentor ,
Dec 10, 2015

Copy link to clipboard

Copied

Sean, I wish I knew of some (free) turnkey resources, but I really don't. I think most people figure it out the way you are... piece by piece. Structure is more of a toolset than a method... you use it to build the workflow that you need. From the questions you ask, I think you are on your way to success. In lieu of anything better, just feel free to stop by with questions anytime.

Russ

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Dec 10, 2015 0
Seanb_us LATEST
Contributor ,
Dec 10, 2015

Copy link to clipboard

Copied

Thanks! willdo.

Likes

Translate

Translate

Report

Report
Community Guidelines
Be kind and respectful, give credit to the original source of content, and search for duplicates before posting. Learn more
Reply
Loading...
Dec 10, 2015 0