TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
A little background: I'm working at a software company where we produce our documentation in DITA/XML files that are stored in the same repository as product code. At build time, our files are wrapped up with hundreds of Java files that describe the APIs. The documentation is installed with the product and opens in HTML, with the APIs appearing on one of the browser tabs.
The API files have been written over the last 20 years by multiple engineers. I've been asked to clean up some of the inconsistencies in spelling and formatting, in my spare time. In these Java files, the lines that appear in documentation are commented out, that is, they begin with /**, followed by * on each successive line, and end with */. In the HTML output, a class name is followed by a brief description, then smaller headings introduce Fields, Constructors, and Methods. Two columns format the content after each of these smaller headings. The left column for Methods, for example, shows the name of a method, the right column describes what the method does. Its parameters are introduced with the word Parameters:, followed by a bulleted list; what the method returns is introduced with… you get the idea.
My Problem Today: One class evaluates arithmetic functions. Apparently, the engineer who documented this class wanted to begin each line of the description with a word in bold font, followed by text. He used this formatting:
/**
* This evaluator supports these arithmetic functions:
* <p>
* <b>Function Name:</b> ADD<br />
* <b>Arguments:</b> num1, num2 (Must be convertible to double.)<br />
* <b>Description:</b> num1 + num2
* </p>
*… etc.
When this formatting is converted to HTML, it appears on the right-hand column looks like this:
This evaluator supports these arithmetic functions:
Function Name: ADD<br /> Arguments: num1, num2 (Must be
convertible to double.)<br />Description: num1 + num2
I've been asked to make the <br /> disappear. The engineer in charge of making builds work suggested, in an email, that I try using <br />: instead.
He's in a different time zone, so I can't question him directly. I'm hoping someone in this group can give me some insight into what this (<br />:) stuff is and, if that doesn't work, what else I might use.
Karen
"Let us read and let us dance ... two amusements that will never do any harm to the world."-- Voltaire
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.
Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.
