settingsLogin | Registersettings

Re: [OpenStack-docs] Anchor tag conventions

0 votes

On 05/14/2015 08:21 AM, Meg McRoberts wrote:

Are you saying to not use the :ref: construction?

I was suggesting to use the :doc: construct for file links. We haven't
added that yet to the markup conventions page but I prefer that for
these kind of links.

Also, I would only add anchors if they are needed, so don't add them by
default everywhere...

Btw. I like having some convention on these, so please rework it and
then let's get it into the wiki,

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@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
asked May 14, 2015 in openstack-docs by Andreas_Jaeger (17,140 points)   2 3 4

3 Responses

0 votes

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@justwriteclick.com>
*To:* Andreas Jaeger <aj@suse.com>
*Cc:* Meg McRoberts <dreidellhasa@yahoo.com>;
"openstack-docs@lists.openstack.org"
<openstack-docs@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@suse.com
<mailto:aj@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@lists.openstack.org
    <mailto:OpenStack-docs@lists.openstack.org>
    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs




--
Anne Gentle
annegentle@justwriteclick.com <mailto:annegentle@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


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 15, 2015 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts dreidellhasa@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@suse.com
To: Meg McRoberts dreidellhasa@yahoo.com; Anne Gentle <
annegentle@justwriteclick.com>
Cc: "openstack-docs@lists.openstack.org" <
openstack-docs@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@justwriteclick.com
To: Andreas Jaeger aj@suse.com
Cc: Meg McRoberts dreidellhasa@yahoo.com;
"openstack-docs@lists.openstack.org"
openstack-docs@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@suse.com
aj@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@lists.openstack.org
   <mailto:OpenStack-docs@lists.openstack.org>

http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@justwriteclick.com annegentle@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@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 15, 2015 by annegentle_at_justwr (9,780 points)   2 5 6
0 votes

Sorry for coming late to this conversation, I agree with Anne here.

L

On 15 May 2015, at 5:44 am, Anne Gentle annegentle@justwriteclick.com wrote:

On Fri, May 15, 2015 at 1:52 AM, Meg McRoberts dreidellhasa@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@suse.com
To: Meg McRoberts dreidellhasa@yahoo.com; Anne Gentle annegentle@justwriteclick.com
Cc: "openstack-docs@lists.openstack.org" openstack-docs@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@justwriteclick.com
To: Andreas Jaeger aj@suse.com
Cc: Meg McRoberts dreidellhasa@yahoo.com;
"openstack-docs@lists.openstack.org"
openstack-docs@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@suse.com
aj@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@lists.openstack.org
   <mailto:OpenStack-docs@lists.openstack.org>
   http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

--
Anne Gentle
annegentle@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@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

responded May 15, 2015 by Lana_Brindley (6,210 points)   2 3 3
...