[OpenStack-docs] Anchor tag conventions
Meg McRoberts
dreidellhasa at yahoo.com
Fri May 15 17:56:22 UTC 2015
Thanks, all! I just replaced that sentence in the https://wiki.openstack.org/wiki/Documentation/Structure#Source_file_namesfile. And I'm going to rename the files in the ha-guide skeleton before anything gets merged.
meg
From: Anne Gentle <annegentle at justwriteclick.com>
To: Meg McRoberts <dreidellhasa at yahoo.com>
Cc: Andreas Jaeger <aj at suse.com>; "openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>
Sent: Friday, May 15, 2015 5:44 AM
Subject: Re: [OpenStack-docs] Anchor tag conventions
On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts <dreidellhasa at yahoo.com> wrote:
I'm quite comfortable going forward with no standards for labels at this point. At some time in the future,we may need standards but we can figure it out then. I just wanted to be sure I wasn't violating any establishedrules.
Out of all this discussion, I would propose a single change to the following section:
Source file names
For XML file names, we have used prefixes like bk_, ch_, section_, and app_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. However, in migrating to RST/Sphinx we are using the xml:id for the file name and moving towards a page-based, topical approach to file naming. Continue to use underbar as the space delimiter.
I would like to replace the highlighted sentence with "RST files should use a hyphen as the space delimiter and have the .rst extension."
That solves my current issues.
It might be nice to expand this section, however, to explain things like the source subdirectory, the index.rst file, the toctree: stuff within the source files, and so forth.''I can work on some of that if you think it is useful.
I'm a fan of both standards and hyphen, though it's totally possible I wrote the "underbar continuation rule" due to xml:id consistency. However, now that we see how the redirects are working, and that the xml:id isn't crucial, let's go with hyphen as a standard.
Thanks!Anne
meg
From: Andreas Jaeger <aj at suse.com>
To: Meg McRoberts <dreidellhasa at yahoo.com>; Anne Gentle <annegentle at justwriteclick.com>
Cc: "openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org>
Sent: Thursday, May 14, 2015 11:19 PM
Subject: Re: [OpenStack-docs] Anchor tag conventions
On 05/15/2015 01:05 AM, Meg McRoberts wrote:
> So it's okay to use hyphens rather than underscores in file names? The
> last line of "Source File Names" in
> https://wiki.openstack.org/wiki/Documentation/Structure
> says "Continue to use underbar as the space delimiter." May I modify
> the spec? And then I will rename the
> ha-guide files before they get merged.
Please write down again what you propose and then let's change the file...
>
> I guess it is just me who thought that each file should have a
> label/anchor for the top-level heading. Andreas said that
> we can use "doc" to reference these docs instead. My problem is that I
> have never been able to figure out what
> to use as the file name for :doc: -- the Sphinx documentation doesn't
> make sense to me.
The openstack-manuals RST files like the user-guide use :doc: already,
have a look a the repo.
> Is there a reason we are using the term "anchor" instead of the term
> "label" that the Sphinx/RST docs use?
>
> And do we need conventions for the content of labels/anchors? The
> ha-guide is in its own repo so I don't anticipate
> any problems but it might be good to have some sort of convention since
> a label/anchor must be unique for the entire
> set -- I can see the potential for conflicts on terms like install,
> troubleshoot, et cetera...
Our conventions apply to all repos to make reviewing and appearance
consistent.
Labels are unique within a single manual, so that should be fine in general.
I don't know whether we need a convention on format of it. Feel free to
propose something,
Andreas
>
> meg
>
> ------------------------------------------------------------------------
> *From:* Anne Gentle <annegentle at justwriteclick.com>
> *To:* Andreas Jaeger <aj at suse.com>
> *Cc:* Meg McRoberts <dreidellhasa at yahoo.com>;
> "openstack-docs at lists.openstack.org"
> <openstack-docs at lists.openstack.org>
> *Sent:* Thursday, May 14, 2015 5:58 AM
> *Subject:* Re: [OpenStack-docs] Anchor tag conventions
>
>
>
> On Thu, May 14, 2015 at 12:30 AM, Andreas Jaeger <aj at suse.com
> <mailto:aj at suse.com>> wrote:
>
> On 05/13/2015 11:50 PM, Meg McRoberts wrote:
>
> Hi all,
> I am creating files for the ha-guide content and have a
> question about
> what the OpenStack docs call
> "embedded anchor pointers" and the Sphinx docs call labels.
> Basically,
> this is the string that you use
> in a :ref: construct to link to a section. It is coded just
> above the
> section title. For example:
>
> .. _anchor-for-ha-intro:
>
> ============================================
> Introduction to Highly Available OpenStack environments
> ============================================
>
> It makes sense to use the file name (minus the .rst
> extension) for the
> labels, except that the Structure
> standard specifies using underbar as the space delimiter,
> and underbars
> in these labels can confuse
> Sphinx.
>
> I would suggest one of the following:
>
> - Use hyphen rather than underscore for RST source file
> names, then use
> that name as the top-level label
> for that section, so the filename would be intro-ha.rst
> rather than
> intro_ha.rst (preferred)
> - Replace the underbars in file names with hyphens for labels.
>
> What does everyone else think?
>
>
> For file names, yes hyphens.
>
> Unless you are linking to a heading lower down in the file, I don't
> believe the label is required. I wonder why those are being added?
>
>
> You can reference files by name, can't you?
>
>
> The anchor convention is for linking within a longer file. But maybe
> the labels offer something? I'd rather always reference whole files
> by name.
>
>
> Andreas
> --
> Andreas Jaeger aj@{suse.com <http://suse.com/>,opensuse.org
> <http://opensuse.org/>} Twitter/Identica: jaegerandi
> SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
> GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham
> Norton,
> HRB 21284 (AG Nürnberg)
> GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C
> C272 A126
>
>
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> <mailto:OpenStack-docs at lists.openstack.org>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
>
>
> --
> Anne Gentle
> annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126
--
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150515/4e94a328/attachment-0001.html>
More information about the OpenStack-docs
mailing list