On Tue, Mar 18, 2014 at 4:35 AM, Jan Rusnacko <jrusnack@xxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxxxxxx
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="" href="https://www.ietf.org/rfc/rfc2616.txt">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
-- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
