Open Stack

So it's okay to use hyphens rather than underscores in file names?  The last line of "Source File Names" inhttps://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 theha-guide files before they get merged.  

I guess it is just me who thought that each file should have a label/anchor for the top-level heading.  Andreas said thatwe can use "doc" to reference these docs instead.  My problem is that I have never been able to figure out whatto use as the file name for :doc: -- the Sphinx documentation doesn't make sense to me.
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 anticipateany problems but it might be good to have some sort of convention since a label/anchor must be unique for the entireset -- I can see the potential for conflicts on terms like install, troubleshoot, et cetera...
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> 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,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
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs




-- 
Anne Gentle
annegentle at justwriteclick.com

   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150514/318affa6/attachment.html>