From jrusnack at redhat.com Thu Jun 4 22:31:30 2015 Content-Type: multipart/mixed; boundary="===============3821802011584115991==" MIME-Version: 1.0 From: Jan Rusnacko To: docs at lists.fedoraproject.org Subject: References to external resources Date: Tue, 18 Mar 2014 11:35:01 +0100 Message-ID: <53282155.6060705@redhat.com> --===============3821802011584115991== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 muc= h like: https://docs.fedoraproject.org/en-US/index.html Downside is that references are attached to the whole section. In case I wa= nt 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-Sec= urity_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 lik= e 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 --===============3821802011584115991==-- From me at petetravis.com Thu Jun 4 22:31:30 2015 Content-Type: multipart/mixed; boundary="===============1293213009375562941==" MIME-Version: 1.0 From: Pete Travis To: docs at lists.fedoraproject.org Subject: Re: References to external resources Date: Tue, 18 Mar 2014 16:02:32 -0600 Message-ID: In-Reply-To: 53282155.6060705@redhat.com --===============1293213009375562941== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable On Tue, Mar 18, 2014 at 4:35 AM, Jan Rusnacko 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= ecurity_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(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 ....
Further reading RFC 2616 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 IETF RFC 2616. ..... 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 --===============1293213009375562941== Content-Type: text/html MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: attachment; filename="attachment.html" PGRpdiBkaXI9Imx0ciI+PGRpdiBjbGFzcz0iZ21haWxfZXh0cmEiPjxkaXYgY2xhc3M9ImdtYWls X3F1b3RlIj5PbiBUdWUsIE1hciAxOCwgMjAxNCBhdCA0OjM1IEFNLCBKYW4gUnVzbmFja28gPHNw YW4gZGlyPSJsdHIiPiZsdDs8YSBocmVmPSJtYWlsdG86anJ1c25hY2tAcmVkaGF0LmNvbSIgdGFy Z2V0PSJfYmxhbmsiPmpydXNuYWNrQHJlZGhhdC5jb208L2E+Jmd0Ozwvc3Bhbj4gd3JvdGU6PGJy Pgo8YmxvY2txdW90ZSBjbGFzcz0iZ21haWxfcXVvdGUiIHN0eWxlPSJtYXJnaW46MHB4IDBweCAw cHggMC44ZXg7Ym9yZGVyLWxlZnQ6MXB4IHNvbGlkIHJnYigyMDQsMjA0LDIwNCk7cGFkZGluZy1s ZWZ0OjFleCI+SGVsbG8sPGJyPgo8YnI+CkkgYW0gbG9va2luZyBpbnRvIHRoZSBwcmVmZXJyZWQg d2F5IGhvdyB0byBtYWtlIHJlZmVyZW5jZXMgdG8gZXh0ZXJuYWw8YnI+CnJlc291cmNlcy4gU28g ZmFyLCBJIGhhdmUgdXNlZCBzZXBhcmF0ZSBzZWN0aW9uIHdpdGggaXRlbWl6ZWRsaXN0LCB2ZXJ5 IG11Y2ggbGlrZTo8YnI+Cjxicj4KPGEgaHJlZj0iaHR0cHM6Ly9kb2NzLmZlZG9yYXByb2plY3Qu b3JnL2VuLVVTL2luZGV4Lmh0bWwiIHRhcmdldD0iX2JsYW5rIj5odHRwczovL2RvY3MuZmVkb3Jh cHJvamVjdC5vcmcvZW4tVVMvaW5kZXguaHRtbDwvYT48YnI+Cjxicj4KRG93bnNpZGUgaXMgdGhh dCByZWZlcmVuY2VzIGFyZSBhdHRhY2hlZCB0byB0aGUgd2hvbGUgc2VjdGlvbi4gSW4gY2FzZSBJ IHdhbnQgdG88YnI+CnJlZmVyIHRvIGV4dGVybmFsIHJlc291cmNlIGZyb20gdGhlIHRleHQsIEkg Y291bGQgdXNlIGZvb3Rub3RlcyBsaWtlIGluOjxicj4KPGJyPgo8YSBocmVmPSJodHRwczovL2Rv Y3MuZmVkb3JhcHJvamVjdC5vcmcvZW4tVVMvRmVkb3JhLzE5L2h0bWwvU2VjdXJpdHlfR3VpZGUv Y2hhcC1TZWN1cml0eV9HdWlkZS1TZWN1cml0eV9PdmVydmlldy5odG1sIiB0YXJnZXQ9Il9ibGFu ayI+aHR0cHM6Ly9kb2NzLmZlZG9yYXByb2plY3Qub3JnL2VuLVVTL0ZlZG9yYS8xOS9odG1sL1Nl Y3VyaXR5X0d1aWRlL2NoYXAtU2VjdXJpdHlfR3VpZGUtU2VjdXJpdHlfT3ZlcnZpZXcuaHRtbDwv YT48YnI+Cgo8YnI+ClRoZXNlIGFyZSBiYXJlbHkgdmlzaWJsZSBhbmQgZG9uYHQgd29yayB3ZWxs IGluIHRleHQgLSBzZWUgZm9vdG5vdGUgWzFdIG9yIFsyXTxicj4KaW4gU2VjdXJpdHkgR3VpZGUg YWJvdmUuPGJyPgo8YnI+ClRoZSBvbmx5IG90aGVyIHdheSBJIGNhbiBub3cgdGhpbmsgb2YgaXMg dG8gdmVyYm9zZWx5IHJlZmVyIHRvIGV4dGVybmFsPGJyPgpyZXNvdXJjZXMsIGUuZy4gJnF1b3Q7 Li4uIChzZWUgUkZDIDI2MTYpJnF1b3Q7IHdpdGggdWxpbmsgdG8gcmZjLiBIb3dldmVyLCBJIGFs c28gbGlrZSB0bzxicj4Ka2VlcCBhbGwgcmVsZXZhbnQgcmVmZXJlbmNlcyB0b2dldGhlciwgc28g SSB3b3VsZCBhbHNvIHVwZGF0ZSBSZWZlcmVuY2VzPGJyPgpzZWN0aW9uLCB3aGljaCB3b3JrcyBi dXQgaXRzIG5vdCBhIGZvb3Rub3RlLCBzbyBsYWNrcyBiYWNrcmVmZXJlbmNlIHRvIHRleHQuPGJy Pgo8YnI+CldoYXQgaXMgeW91ciBwcmVmZXJyZWQgd2F5IHRvIG1ha2UgcmVmZXJlbmNlcyA/PGJy Pgo8YnI+ClRoYW5rIHlvdSw8YnI+Ckphbjxicj4KPHNwYW4gY2xhc3M9IiI+PGZvbnQgY29sb3I9 IiM4ODg4ODgiPi0tPGJyPgpkb2NzIG1haWxpbmcgbGlzdDxicj4KPGEgaHJlZj0ibWFpbHRvOmRv Y3NAbGlzdHMuZmVkb3JhcHJvamVjdC5vcmciPmRvY3NAbGlzdHMuZmVkb3JhcHJvamVjdC5vcmc8 L2E+PGJyPgpUbyB1bnN1YnNjcmliZTo8YnI+CjxhIGhyZWY9Imh0dHBzOi8vYWRtaW4uZmVkb3Jh cHJvamVjdC5vcmcvbWFpbG1hbi9saXN0aW5mby9kb2NzIiB0YXJnZXQ9Il9ibGFuayI+aHR0cHM6 Ly9hZG1pbi5mZWRvcmFwcm9qZWN0Lm9yZy9tYWlsbWFuL2xpc3RpbmZvL2RvY3M8L2E+PC9mb250 Pjwvc3Bhbj48L2Jsb2NrcXVvdGU+PC9kaXY+PGJyPjxicj48L2Rpdj48ZGl2IGNsYXNzPSJnbWFp bF9leHRyYSI+PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj4KSSAqdGhpbmsqIHlv dSBjYW4gYWRkIHJlZmVyZW5jZXMgdG8gYW55IHN0cnVjdHVyYWwgdHlwZSBlbGVtZW50LCBpZTo8 YnI+PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj4uLi4gZm9yIG1vcmUgaW5mb3Jt YXRpb24sIHNlZSAmbHQ7eHJlZiBsaW5rZW5kPSZxdW90O2NoYXB0ZXJfbmFtZS1mdXJ0aGVyX3Jl YWRpbmctUkZDMjYxNiZxdW90OyAvJmd0Ozxicj4uLi4uPGJyPjxicj4KPC9kaXY+PGRpdiBjbGFz cz0iZ21haWxfZXh0cmEiPiZsdDtzZWN0aW9uIGlkPSZxdW90O2NoYXB0ZXJfbmFtZS1mdXJ0aGVy X3JlYWRpbmcmcXVvdDsmZ3Q7PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj6goCAm bHQ7dGl0bGUmZ3Q7RnVydGhlciByZWFkaW5nJmx0Oy90aXRsZSZndDs8YnI+PC9kaXY+PGRpdiBj bGFzcz0iZ21haWxfZXh0cmEiPqCgoKCgICZsdDtmb3JtYWxwYXJhIGlkPSZxdW90O2NoYXB0ZXJf bmFtZS1mdXJ0aGVyX3JlYWRpbmctUkZDMjYxNiZxdW90OyZndDs8YnI+CjwvZGl2PjxkaXYgY2xh c3M9ImdtYWlsX2V4dHJhIj6goKCgoKCgoCAmbHQ7dGl0bGUmZ3Q7UkZDIDI2MTYmbHQ7L3RpdGxl Jmd0Ozxicj48L2Rpdj48ZGl2IGNsYXNzPSJnbWFpbF9leHRyYSI+oKCgoKCgoKAgJmx0O3BhcmEm Z3Q7PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj6goKCgoKCgoKCgoCBVbmRlcnN0 YW5kaW5nIHRoZSBIVFRQIHNwZWNpZmljYXRpb24gaXMgdml0YWwgd2hlbiBkZXZlbG9waW5nIHNl Y3VyZSB3ZWIgYXBwbGljYXRpb25zLqAgVGhlIG1lY2hhbmlzbSBvZiBjbGllbnQtc2VydmVyIGNv bW11bmljYXRpb24gYW5kIHRoZSBuZWdvdGlhdGlvbiBvZiBzZWN1cmUgY29ubmVjdGlvbnMgYXJl IG91dGxpbmVkIGluICZsdDt1bGluayB1cmw9JnF1b3Q7PGEgaHJlZj0iaHR0cHM6Ly93d3cuaWV0 Zi5vcmcvcmZjL3JmYzI2MTYudHh0Ij5odHRwczovL3d3dy5pZXRmLm9yZy9yZmMvcmZjMjYxNi50 eHQ8L2E+JnF1b3Q7Jmd0O0lFVEYgUkZDIDI2MTYmbHQ7L3VsaW5rJmd0Oy48YnI+CjwvZGl2Pjxk aXYgY2xhc3M9ImdtYWlsX2V4dHJhIj6goKCgoKCgoCAmbHQ7L3BhcmEmZ3Q7PGJyPjwvZGl2Pjxk aXYgY2xhc3M9ImdtYWlsX2V4dHJhIj6goKCgoCAmbHQ7L2Zvcm1hbHBhcmEmZ3Q7PGJyPjxicj4u Li4uLjxicj48YnI+PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj5UaGF0IG1pZ2h0 IGJlIG92ZXJraWxsIGZvciBhIGJ1bGxldGVkIGxpc3Qgb2YgbGlua3MsIGFuZCBldmVuIHdpdGgg dGhlIGNvbnRleHQsIGl0IHdvbiYjMzk7dKAgaGF2ZSB0aGUgZWZmZWN0IG9mIGJyaW5naW5nIHRo ZSB1c2VyICZxdW90O2RpcmVjdGx5JnF1b3Q7IHRvIHRoZSBsaW5rIChhdCBsZWFzdCBub3Qgd2l0 aCAmIzM5O2h0bWwmIzM5OyBmb3JtYXQpPGJyPgo8YnI+PC9kaXY+PGRpdiBjbGFzcz0iZ21haWxf ZXh0cmEiPkkgdHlwaWNhbGx5IHB1dCBsaW5rcyBpbmxpbmUsIGJ1dCBoYXZpbmcgdGhlbSBhZ2dy ZWdhdGVkIGF0IHRoZSBlbmQgb2YgYSBzZWN0aW9uIGlzIGFwcGVhbGluZy6gIEkgZG9uJiMzOTt0 IHJlY2FsbCBvZmZoYW5kIGlmIG91ciBzdHlsZSBjb252ZW50aW9ucyBwcmVmZXIgb25lIHdheSBv ciB0aGUgb3RoZXI7IHBlcmhhcHMgc29tZW9uZSBtb3JlIGV4cGVyaWVuY2VkIGNhbiBzcGVhayB1 cC48YnI+Cjxicj48L2Rpdj48ZGl2IGNsYXNzPSJnbWFpbF9leHRyYSI+LS1QZXRlPGJyPjwvZGl2 PjxkaXYgY2xhc3M9ImdtYWlsX2V4dHJhIj48YnI+PGJyPjwvZGl2PjxkaXYgY2xhc3M9ImdtYWls X2V4dHJhIj6goCA8YnI+PC9kaXY+PC9kaXY+Cg== --===============1293213009375562941==-- From sparks at fedoraproject.org Thu Jun 4 22:31:31 2015 Content-Type: multipart/mixed; boundary="===============6873669141895782246==" MIME-Version: 1.0 From: Eric Christensen To: docs at lists.fedoraproject.org Subject: Re: References to external resources Date: Mon, 24 Mar 2014 13:21:32 -0400 Message-ID: <20140324172132.GB10113@localhost.localdomain> In-Reply-To: 53282155.6060705@redhat.com --===============6873669141895782246== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable -----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] o= r [2] > in Security Guide above. Yeah, this is a problem in the brand. I should probably file a bug for thi= s 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 l= ike to > keep all relevant references together, so I would also update References > section, which works but its not a footnote, so lacks backreference to te= xt. +1 The links get pulled out in the PDF version, though, so we'll be back to ex= ternally shown links. > What is your preferred way to make references ? Still trying to find one. What you found in the Security Guide was an expe= riment. :/ - -- 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=3D=3D =3Drm2O -----END PGP SIGNATURE----- --===============6873669141895782246==-- From jrusnack at redhat.com Thu Jun 4 22:31:31 2015 Content-Type: multipart/mixed; boundary="===============7716183100214983152==" MIME-Version: 1.0 From: Jan Rusnacko To: docs at lists.fedoraproject.org Subject: Re: References to external resources Date: Mon, 24 Mar 2014 20:53:39 +0100 Message-ID: <53308D43.2020001@redhat.com> In-Reply-To: 20140324172132.GB10113@localhost.localdomain --===============7716183100214983152== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 -------------------------------------------------- >=20 --===============7716183100214983152==--