Bug 485372 - Need ability to create internal cross reference without a section label
Need ability to create internal cross reference without a section label
Status: CLOSED NOTABUG
Product: Publican
Classification: Community
Component: publican (Show other bugs)
1.6
All Linux
high Severity medium
: ---
: ---
Assigned To: Jeff Fearn
Fedora Extras Quality Assurance
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2009-02-12 22:51 EST by Deon Ballard
Modified: 2010-11-23 23:19 EST (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2009-03-11 23:49:57 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:


Attachments (Terms of Use)

  None (edit)
Description Deon Ballard 2009-02-12 22:51:22 EST
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" />
Comment 1 Jeff Fearn 2009-02-17 01:19:53 EST
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.
Comment 2 Deon Ballard 2009-02-17 11:31:01 EST
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.
Comment 3 Jeff Fearn 2009-02-17 16:43:15 EST
(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.
Comment 4 Deon Ballard 2009-02-17 18:14:24 EST
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.
Comment 5 Jeff Fearn 2009-02-25 00:00:28 EST
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.

Note You need to log in before you can comment on or make changes to this bug.