From me at petetravis.com Thu Jun 4 22:31:30 2015 Content-Type: multipart/mixed; boundary="===============6864943201205432910==" 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 --===============6864943201205432910== 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 --===============6864943201205432910== 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== --===============6864943201205432910==--