5:35 a.m.
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-S...
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
5:02 p.m.
On Tue, Mar 18, 2014 at 4:35 AM, Jan Rusnacko <jrusnack(a)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-S...
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(a)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
12:21 p.m.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
On Tue, Mar 18, 2014 at 11:35:01AM +0100, Jan Rusnacko wrote:
These are barely visible and don`t work well in text - see footnote
[1] or [2]
in Security Guide above.
Yeah, this is a problem in the brand. I should probably file a bug for this so we can
formally look at it.
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.
+1
The links get pulled out in the PDF version, though, so we'll be back to externally
shown links.
What is your preferred way to make references ?
Still trying to find one. What you found in the Security Guide was an experiment. :/
- -- Eric
- --------------------------------------------------
Eric "Sparks" Christensen
Fedora Project
sparks(a)fedoraproject.org - sparks(a)redhat.com
097C 82C3 52DF C64A 50C2 E3A3 8076 ABDE 024B B3D1
- --------------------------------------------------
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1
iQGcBAEBCgAGBQJTMGmZAAoJEB/kgVGp2CYvBMwMAJc6Zq7Kngq9j5JrBUso9Jbe
J+1f2zjwM3FNXII/FKJFq40p4m2j45VdZK2wFOL+OkeC+ZykmRzDcdrEQuq1WRBB
659e5p5sg6g7YQscvHhYpDxX+BYSIbqvaSggC+1YRK0SMjGfDu47cYQCVa7/VxQI
PxnzbWt44bGGxQIl4cOczZp2qbK7ud+hXegptO+C+rN4YIggGUFAe8DbkzsrKprh
6ZwxCsd5usItbNRyj4zGaeeTJm5lic/mLShlrEBtKd16FuLEx9xxwul5l6lnjlAE
SwSr6XM0NYwFnWMqZ1zloi8slqiwktWdwsgIo6oDtWIsFb4Eh0B8TL7UYpxdYQDQ
fG6TWMCag6glTcVw33ZXM2LzF96lBmtci+UmRPQ+N2JdGS52NYGArK/mm9NLeNiL
Vhl93Lu8G7mVRsGHl8j9PCs6Jf3VtkPeQYeFahU9mUBdC9z/xHarvxhdJvRrE7y+
q7K/kaoq6km1DqcrHfHHmDXWT0eRPmb0nDZCllkgxA==
=rm2O
-----END PGP SIGNATURE-----
2:53 p.m.
Pete, Eric: thank you guys for your responses !
On 03/24/2014 06:21 PM, Eric H. Christensen wrote:
On Tue, Mar 18, 2014 at 11:35:01AM +0100, Jan Rusnacko wrote:
> These are barely visible and don`t work well in text - see footnote [1]
> or [2] in Security Guide above.
Yeah, this is a problem in the brand. I should probably file a bug for
this so we can formally look at it.
> 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.
+1
The links get pulled out in the PDF version, though, so we'll be back to
externally shown links.
> What is your preferred way to make references ?
Still trying to find one. What you found in the Security Guide was an
experiment. :/
-- Eric
-------------------------------------------------- Eric "Sparks"
Christensen Fedora Project
sparks(a)fedoraproject.org - sparks(a)redhat.com 097C 82C3 52DF C64A 50C2 E3A3
8076 ABDE 024B B3D1 --------------------------------------------------
3702
days inactive
3708
days old
3 comments
3 participants
participants (3)
-
Eric Christensen -
Jan Rusnacko -
Pete Travis