[OpenStack-docs] Anchor tag conventions
Lana Brindley
openstack at lanabrindley.com
Fri May 15 17:41:25 UTC 2015
Sorry for coming late to this conversation, I agree with Anne here.
L
On 15 May 2015, at 5:44 am, Anne Gentle <annegentle at justwriteclick.com> wrote:
>
>
> 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 established
> rules.
>
> 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
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150515/6bc66aee/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 496 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150515/6bc66aee/attachment-0001.pgp>
More information about the OpenStack-docs
mailing list