I need a way to create an internal cross reference which doesn't automatically fill in the term "section" and then the number and all the associated punctuation, like: Section 1.1.1. "My Awesome Title" For a lot of my reference docs, I include references in the text, where it is very convenient to have a link to another reference entry, but it is pointlessly distracting to make everything a "Section" reference. Something like: When using the Example object class, consider setting the /example-attribute/ and the /other-attribute/ since this increases performance. With the current publican restrictions, this comes out: When using the Example object class, consider setting the Section 1.1.1 "example-attribute" and Section 1.1.2 "other-attribute" since this increases performance. Or I can not include links, which makes the reader have to do a ton of clicking to get the same information, or I can use an absolute ulink to the HTML page, which is silly and not sustainable. Previously, there were at least two ways to do this: 1. <link /> 2. <xref ... endterm="my choice" />
Formal para allows this. <formalpara id="My_Formal_Para"> <title>My Formal Para</title> <para> Cheese is yummy </para> </formalpara> ... <para> See <xref linkend="My_Formal_Para"/> for the story of my formal para! </para> If you include some sample XML I'd be able to get a better idea of what your usage is; there may be other approaches that don't break translation like link and endterm do.
I can't use formalpara; these are actual sections. This is a reference guide for plugins. The original docs, for example, look like this: http://www.redhat.com/docs/manuals/dir-server/plugin/7.1/datatype.htm#1003100 That's a table; if you scroll down a little, you can see the inline cites and the see alsos. Throughout the guide, there are tables with cross references, "see also" section, and inline links within sentences that point to the reference section for the plubin (or function, or paramteer block, etc, depending). However, the reference section to which the cross links point is a section. Wouldn't it be possible to put a warning on link or some other tag, that using it could break translations (and why, exactly?) without completely blocking the tag? I can't imagine every single person in the world who uses publican (not just at RH, but the whole community) will translate their docs. I don't see the problem in giving people a little more flexibility in what they can use.
(In reply to comment #2) > I can't use formalpara; these are actual sections. This is a reference guide > for plugins. The original docs, for example, look like this: > > http://www.redhat.com/docs/manuals/dir-server/plugin/7.1/datatype.htm#1003100 There is little visual difference between that and what a group of formal paras would look like. Without the actual XML I can only guess at why you want a bunch of sections to look and act like a bunch of formal paras. > That's a table; if you scroll down a little, you can see the inline cites and > the see alsos. > > Throughout the guide, there are tables with cross references, "see also" > section, and inline links within sentences that point to the reference section > for the plubin (or function, or paramteer block, etc, depending). However, the > reference section to which the cross links point is a section. > > Wouldn't it be possible to put a warning on link or some other tag, that using > it could break translations (and why, exactly?) without completely blocking the > tag? I can't imagine every single person in the world who uses publican (not > just at RH, but the whole community) will translate their docs. I don't see the > problem in giving people a little more flexibility in what they can use. Please read the FAQ chapter in the Publican Users Guide about STRICT brands.
I don't want them to look like formalparas. I want the sections to look like sections. I want the xref to not have a section label. You don't need to guess why I want them to act like formalparas; I told you. I have links, inline in sentences and in tables, which were originally without section numbering, so the link functions are part of the text. As in, people read "You can use slapi_ch_array_free to free memory in the array," and "slapi_ch_array_free" was a link to the reference section for slapi_ch_array_free. Currently with xref, it reads "You can use Section 15.38, 'slapi_ch_array_free' to free memory in the array," I just wanted a way to work around that. All the FAQ says is that RH styles are STRICT.
Auto labelling is mandatory in Red Hat brands, if you aren't willing to consider other ways of tagging your content there is no solution.