Level rules for nested codeblocks

[Guest]

I am trying to modify the level rules to apply indentation to codeblock elements, which I have allowed for nesting so we can create good code samples.

I have my level rules set up like this, but everything is still flush with the left margin when I am authoring:

Text format rules

If level is: 1

Basic properties

Indents

First indent: 0

Else, if level is: 2

Basic properties

Indents

Move first indent by: +0.5”

Else, if level is: 3

Basic properties

Indents

Move first indent by: +0.10”

Else, if level is: 4

Basic properties

Indents

Move first indent by: +0.15”

Anyone who's done this more often than me have any ideas? I have tried with both a FirstIndent, FirstIndentChange, LeftIndent, and LeftIndent change and whenever I apply the element definitions to my topic it still does not work.

[ScottPrentice]

Hi Kel/y_H ..

In theory, what you're showing should work, so it may be the "Count Ancestors Named" value that's not right. Are you really nesting clodeblocks? Is this DITA (DITA doesn't allow codeblock to contain another codeblock)? Or are you referring to codeblocks nested within some other element (like a list) that you're trying to indent?

I assume that you're not doing this to add indenting to lines within a code sample .. right? Some people try to apply a codeblock tag to each line in a code sample, then use styling to adjust the indent ..

[codeblock]first line[/codeblock]

[codeblock]next line[/codeblock]

[codeblock]last line[/codeblock]

If you're doing this, you might look into putting all of the code into a single codeblock and use forced line breaks (SHIFT+ENTER) to separate the lines ..

[codeblock]first line

next line

last line[/codeblock]

Any indenting within the codeblock would be handled by adding the proper number of leading spaces to each line.

Give us more info about what you're doing, and we might be able to help.

Cheers,

...scott

[Guest]

Thanks, Scott! This was helpful.

Yes, we are really nesting codeblocks - we (read: me) modified the EDD to make it allowable, which I suppose could be part of the problem. It works great when we generate our output - we just apply a margin in the CSS and it does all the work to indent everything properly as long as its nested structure is correct. The problem comes in where people are authoring, because they can't get a good look of what their code samples look like, and we're doing API documentation so we have a lot of code samples.

Any indenting within the codeblock would be handled by adding the proper number of leading spaces to each line.

In FrameMaker, we can't add tabs or more than one space (which I personally like; space characters aren't a great solution), so adding leading space characters wouldn't work well either I imagine.

[ScottPrentice]

Hmm .. well if you are using DITA, then tweaking the EDD (and DTD?) to accommodate nested codeblocks will "break" DITA if you plan to use other tools and make your files available to others. You could specialize [ph] or some other element to achieve the same thing "legally" .. but I'd reccomend against that.

What tool are you using to produce your HTML that accepts this model? I suppose that RoboHelp wouldn't care, but if you're using the DITA-OT, it'll barf since this isn't valid DITA.

Hmm .. I assume that you *are* authoring in XML, not in binary (structured) FM files, right? If you kept the files as binary, then you'd be able to get away with this without modifying the DTDs. (Authoring DITA in FM binary files is also not recommended, as you'll run into trouble down the road.)

To add multiple spaces you need to disable the Smart Space feature .. Format > Document > Text Options :: Smart Spaces .. it's unfortunate that this is burried so deep. (DITA-FMx, the tool I produce for enhanced DITA authoring in FM, has an auto-swithcing feature to flip between Smart Space modes when you place the insertion oping in a codeblock or non-codeblock element.)

Tabs don't work well in XML since most tools will collapse tabs into a space (in theory this shouldn't happen in a "preformatted" element like codeblock, but it does).

I definitely recommend trying to use the standard method for authoring codeblocks, despite the fact that it may not seem like a good idea for your situation. With DITA, it's best to stick with the standard as long as you can.

Cheers,

...scott

Scott Prentice

Leximation, Inc.

www.leximation.com

[Guest]

We're using MadCap Flare, not the Open Toolkit. And yep, we're authoring .xml files not .fm files.

I'll keep digging and see what I can figure out. I hope future DITA specs have some better element solutions around code, especially as more and more companies develop APIs.

[ScottPrentice]

I've not heard of people having issues with needing more elements for code samples. In general, it's just a copy/paste into a codeblock, and all's well. It doesn't seem like the author should be spending much time messing with the code samples.

With DITA 1.2 you can use the coderef element, which lets you just insert a reference to an external code file, and the contents of that file are displayed within the codeblock. Unfortunately, in FM10 and FM11, Adobe hasn't quite implemented this feature properly so it doesn't work as it should .. but in concept this is a great feature.

Cheers,

...scott

[Guest]

Thanks, Scott! I am going to keep exploring, but the coderef could be a good solution for us. I would love to hear from other people using DITA (and specifically structured FrameMaker) for API reference doc.

And I agree, we should not be messing with the code samples. I've been advocating that for awhile!