On Tue, Mar 18, 2014 at 4:35 AM, Jan Rusnacko <jrusnack@redhat.com> wrote:
Hello,

I am looking into the preferred way how to make references to external
resources. So far, I have used separate section with itemizedlist, very much like:

https://docs.fedoraproject.org/en-US/index.html

Downside is that references are attached to the whole section. In case I want to
refer to external resource from the text, I could use footnotes like in:

https://docs.fedoraproject.org/en-US/Fedora/19/html/Security_Guide/chap-Security_Guide-Security_Overview.html

These are barely visible and don`t work well in text - see footnote [1] or [2]
in Security Guide above.

The only other way I can now think of is to verbosely refer to external
resources, e.g. "... (see RFC 2616)" with ulink to rfc. However, I also like to
keep all relevant references together, so I would also update References
section, which works but its not a footnote, so lacks backreference to text.

What is your preferred way to make references ?

Thank you,
Jan
--
docs mailing list
docs@lists.fedoraproject.org
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs



I *think* you can add references to any structural type element, ie:

... for more information, see <xref linkend="chapter_name-further_reading-RFC2616" />
....

<section id="chapter_name-further_reading">
   <title>Further reading</title>
      <formalpara id="chapter_name-further_reading-RFC2616">
         <title>RFC 2616</title>
         <para>
            Understanding the HTTP specification is vital when developing secure web applications.  The mechanism of client-server communication and the negotiation of secure connections are outlined in <ulink url="https://www.ietf.org/rfc/rfc2616.txt">IETF RFC 2616</ulink>.
         </para>
      </formalpara>

.....


That might be overkill for a bulleted list of links, and even with the context, it won't  have the effect of bringing the user "directly" to the link (at least not with 'html' format)

I typically put links inline, but having them aggregated at the end of a section is appealing.  I don't recall offhand if our style conventions prefer one way or the other; perhaps someone more experienced can speak up.

--Pete