Open Stack

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