further convert some bits of the documentation

diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc
index 5b0cc66..21121e1 100644 (file)
--- a/doc/doxygen/platform.doc
+++ b/doc/doxygen/platform.doc
@@ -1,62 +1,11 @@
 /*! @page platform Describing the virtual platform
 
-@tableofcontents
-
-@htmlonly
-<div align="center">
-@endhtmlonly
-@htmlinclude graphical-toc.svg
-@htmlonly
-</div>
-<script>
-document.getElementById("VirtualPlatform").style="opacity:0.93999999;fill:#ff0000;fill-opacity:0.1;stroke:#000000;stroke-width:0.35277778;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1";
-</script>
-@endhtmlonly
-
-As @ref starting_components "explained in the introduction," any
-SimGrid study must entail the description of the platform on which you
-want to simulate your application. You have to describe **each element
-of your platform**, such as computing hosts, clusters, each disks,
-links, etc. You must also define the **routing on your platform**, ie
-which path is taken between two hosts. Finally, you may also describe
-an **experimental scenario**, with qualitative changes (e.g.,
-bandwidth changes representing an external load) and qualitative
-changes (representing how some elements fail and restart over time).
-
-You should really separate your application from the platform
-description, as it will ease your experimental campain afterward.
-Mixing them is seen as a really bad experimental practice. The easiest
-to enforce this split is to put the platform description in a XML
-file. Many example platforms are provided in the archive, and this
-page gives all needed details to write such files, as well as some
-hints and tricks about describing your platform.
-
-On the other side, XML is sometimes not expressive enough for some
-platforms, in particular large platforms exhibiting repetitive
-patterns that are not simply expressed in XML.  In practice, many
-users end up generating their XML platform files from some sort of
-scripts. It is probably preferable to rewrite your XML @ref
-platform_lua "platform using the lua scripting language" instead.
-In the future, it should be possible to describe the platform directly
-in C++, but this is not possible yet.
+
 
 As usual, SimGrid is a versatile framework, and you should find the
 way of describing your platform that best fits your experimental
 practice. 
 
-@section pf_overview Describing the platform with XML
-
-Your platform description should follow the specification presented in
-the [simgrid.dtd](https://simgrid.org/simgrid.dtd)
-DTD file. The same DTD is used for both the platform and deployment
-files.
-
-From time to time, this DTD evolves to introduce possibly
-backward-incompatible changes. That is why each platform desciption is
-enclosed within a @c platform tag, that have a @c version attribute. 
-The current version is <b>4.1</b>. The @c simgrid_update_xml program can
-upgrade most of the past platform files to the recent formalism.
-
 @section pf_first_example First Platform Example 
 
 Here is a very simple platform file, containing 3 resources (two hosts
@@ -79,8 +28,6 @@ and one link), and explicitly giving the route between the hosts.
 </platform>
 @endcode
 
-As we said, the englobing @ref pf_overview "&lt;platform&gt;" tag is
-used to specify the dtd version used for this file.
 
 Then, every resource (specified with @ref pf_tag_host, @ref
 pf_tag_link or others) must be located within a given **networking

diff --git a/docs/source/community.rst b/docs/source/community.rst
index f57ae3a..fe4dadd 100644 (file)
--- a/docs/source/community.rst
+++ b/docs/source/community.rst
@@ -31,9 +31,9 @@ to us and say hello! We love earing about how people use SimGrid.
    list.
  - Join us on IRC and ask your question directly on the channel \#simgrid at
    ``irc.debian.org``
-   (or use the ugly `web interface <https://webchat.oftc.net/?channels=%23simgrid>`_)
+   (or use the ugly `web interface <https://webchat.oftc.net/?channels=%23simgrid>`_
    if you don't have a
-   `real client <https://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients>`_)
+   `real client <https://en.wikipedia.org/wiki/Comparison_of_Internet_Relay_Chat_clients>`_
    installed). When no non-french speaker are connected, we usually
    chat in french on this channel, but we do switch back to english
    when we have a guest.

diff --git a/docs/source/platform.rst b/docs/source/platform.rst
index 6e81d4d..5c99228 100644 (file)
--- a/docs/source/platform.rst
+++ b/docs/source/platform.rst
@@ -37,9 +37,14 @@ with qualitative changes (e.g., bandwidth changes representing an
 external load) and qualitative changes (representing how some elements
 fail and restart over time).
 
+
+
 Defining Basic Elements
 ***********************
 
+These are the components of your platform.
+
+
 There is not much to say about the definition of basic elements. Just
 use the appropriate tags: :ref:`pf_tag_host`, :ref:`pf_tag_link` and
 :ref:`pf_tag_storage`.

diff --git a/docs/source/platform_reference.rst b/docs/source/platform_reference.rst
index d78a23a..70496ce 100644 (file)
--- a/docs/source/platform_reference.rst
+++ b/docs/source/platform_reference.rst
@@ -267,8 +267,26 @@ and a download link.
 :``state_file``: File containing the state profile.
    See the full description in :ref:`pf_tag_host`
 
+.. _pf_tag_platform:
 
-   
+------------------------------------------------------------------
+<platform>
+------------------------------------------------------------------
+
+**Parent tags:** none (this is the root tag of every file) |br|
+**Children tags:** :ref:`pf_tag_config` (must come first),
+:ref:`pf_tag_cluster`, :ref:`pf_tag_cabinet`, :ref:`pf_tag_peer`,
+:ref:`pf_tag_zone`, :ref:`pf_tag_trace`, :ref:`pf_tag_trace_connect` |br|
+**Attributes:** 
+
+:``version``: Version of the DTD, describing the whole XML format.
+             This versionning allow future evolutions, even if we
+             avoid backward-incompatible changes. The current version
+             is **4.1**. The ``simgrid_update_xml`` program can
+             upgrade most of the past platform files to the recent
+             formalism.
+
+             
 .. _pf_tag_prop:
 
 ------------------------------------------------------------------