From e0a281ae9bf022db9aaf5576ae34577bad91c946 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Mon, 4 Mar 2019 22:48:53 +0100 Subject: [PATCH] further convert some bits of the documentation --- doc/doxygen/platform.doc | 55 +----------------------------- docs/source/community.rst | 4 +-- docs/source/platform.rst | 5 +++ docs/source/platform_reference.rst | 20 ++++++++++- 4 files changed, 27 insertions(+), 57 deletions(-) diff --git a/doc/doxygen/platform.doc b/doc/doxygen/platform.doc index 5b0cc668cc..21121e1e29 100644 --- a/doc/doxygen/platform.doc +++ b/doc/doxygen/platform.doc @@ -1,62 +1,11 @@ /*! @page platform Describing the virtual platform -@tableofcontents - -@htmlonly -
-@endhtmlonly -@htmlinclude graphical-toc.svg -@htmlonly -
- -@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 4.1. 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. @endcode -As we said, the englobing @ref pf_overview "<platform>" 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 f57ae3a456..fe4daddf94 100644 --- 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 `_) + (or use the ugly `web interface `_ if you don't have a - `real client `_) + `real client `_ 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 6e81d4d0f6..5c99228835 100644 --- 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 d78a23a1af..70496ce7af 100644 --- 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: - +------------------------------------------------------------------ + +------------------------------------------------------------------ + +**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: ------------------------------------------------------------------ -- 2.20.1