From b6cad10645a8bd15001a7f45b9554131cb9dbd28 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Fri, 10 Nov 2017 10:22:31 +0100
Subject: [PATCH] doc: improve the Writing Content section with more info and
 links.

---
 doc/pelican/writing-content.rst | 59 +++++++++++++++++++++------------
 1 file changed, 38 insertions(+), 21 deletions(-)

diff --git a/doc/pelican/writing-content.rst b/doc/pelican/writing-content.rst
index 7514fdc3..3456d4b3 100644
--- a/doc/pelican/writing-content.rst
+++ b/doc/pelican/writing-content.rst
@@ -40,13 +40,6 @@ documentation provides an extensive syntax guide, the info is scattered across
 many pages. The following page will try to explain the basics and mention a
 bunch of tricks that might not be immediately obvious.
 
-.. note-warning::
-
-    Be sure to read the
-    `Pelican docs about writing content <http://docs.getpelican.com/en/stable/content.html>`_
-    as well to get overview of how Pelican treats the files and various
-    metadata.
-
 .. contents::
     :class: m-block m-default
 
@@ -119,6 +112,10 @@ Example:
     Going back to already used character, reST remembers for which heading
     level it was used the first time, so it goes back to <h2>.
 
+There's more information about
+`basic syntax rules <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#quick-syntax-overview>`_
+in the official :abbr:`reST <reStructuredText>` documentation.
+
 `Metadata fields`_
 -------------------
 
@@ -140,6 +137,12 @@ contents. Consecutive indented lines are treated as part of the same field.
 
     Article content starts here.
 
+See the `Pelican documentation <http://docs.getpelican.com/en/stable/content.html>`_
+for details about recognized fields and how various metadata can be also
+automatically extracted from the filesystem. The
+`m.css Pelican theme <{filename}/pelican/theme.rst>`_ recognizes a few more
+fields.
+
 `Directives`_
 -------------
 
@@ -212,7 +215,7 @@ Example and corresponding output, note the indentation:
 .. note-info::
 
     Please note that the above example code uses some directives provided by
-    m.css `Pelican plugins <{filename}/plugins.rst>`_ that are not builtin in
+    `m.css Pelican plugins <{filename}/plugins.rst>`_ that are not builtin in
     the :abbr:`reST <reStructuredText>` parser itself.
 
 `Interpreted text roles`_
@@ -354,6 +357,9 @@ have lists inside quotes and the like.
     Term 2
         Description of term 2
 
+The official :abbr:`reST <reStructuredText>` documentation has more detailed
+info about `block elements <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#body-elements>`_.
+
 `Basic inline elements`_
 ========================
 
@@ -363,18 +369,25 @@ backtick :rst:`\`` is reserved and you can redefine to whatever you need in
 given scope using the `default-role <http://docutils.sourceforge.net/docs/ref/rst/directives.html#default-role>`_
 directive.
 
-Links are written using :rst:`\`title <URL>\`_`, where *title* is link text and
-*URL* is the link destination. The link title can be then used again to link to
-the same URL as simply :rst:`\`title\`_`. Note that specifying two links with
-the same title and different URLs is an error --- if you need that, use
-anonymous links that are in a form of :rst:`\`title <URL>\`__` (two underscores
-after). It's also possible to wrap section headings in a :rst:`\`heading\`_` to
-make them into clickable headers that you can link to later.
+External links are written using :rst:`\`title <URL>\`_`, where *title* is link
+text and *URL* is the link destination. The link title can be then used again
+to link to the same URL as simply :rst:`\`title\`_`. Note that specifying two
+links with the same title and different URLs is an error --- if you need that,
+use anonymous links that are in a form of :rst:`\`title <URL>\`__` (two
+underscores after).
+
+Internal links: every heading can be linked to using :rst:`\`heading\`_`, where
+*heading* is the heading text, moreover the heading itself can be wrapped in
+backticks and an underscore to make it a clickable link pointing to itself.
+Arbitrary anchors inside the text flow that can be linked to later can be
+created using the :rst:`.. _anchor:` syntax.
 
 .. code-figure::
 
     .. code:: rst
 
+        .. _an anchor:
+
         An *emphasised text*, **strong text** and a ``literal``. Link to
         `Google <https://google.com>`_, `the heading below <#a-heading>`_ or just an
         URL as-is: https://mcss.mosra.cz/.
@@ -384,10 +397,13 @@ make them into clickable headers that you can link to later.
 
         Repeated link to `Google`_. Anonymous links that share the same titles
         `here <http://blog.mosra.cz>`__ and `here <http://magnum.graphics/>`__.
+        Link to `an anchor`_ above.
+
+    .. _an anchor:
 
     An *emphasised text*, **strong text** and a ``literal``. Link to
-    `Google <https://google.com>`_, `the heading below <#a-heading>`_ or just an
-    URL as-is: https://mcss.mosra.cz/.
+    `Google <https://google.com>`_, `the heading below <#a-heading>`_ or just
+    an URL as-is: https://mcss.mosra.cz/.
 
     .. raw:: html
 
@@ -396,15 +412,16 @@ make them into clickable headers that you can link to later.
 
     Repeated link to `Google`_. Anonymous links that share the same titles
     `here <http://blog.mosra.cz>`__ and `here <http://magnum.graphics/>`__.
+    Link to `an anchor`_ above.
 
     .. raw:: html
 
         </section>
 
-.. note-info::
-
-    There are some special features in Pelican for easier linking to internal
-    content. Be sure to `check out the documentation <http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content>`_.
+There are some special features in Pelican for easier linking to internal
+content, be sure to `check out the documentation <http://docs.getpelican.com/en/stable/content.html#linking-to-internal-content>`_.
+The :abbr:`reST <reStructuredText>` documentation also offers more detailed
+info about `inline markup <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup>`_.
 
 `Essential directives`_
 =======================
-- 
2.30.2