Python port of Planète Casio's BBcode translator (mirror from forge.touhey.org).
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

297 lines
9.3KB

  1. The textout BBcode markup language
  2. ==================================
  3. The BBcode markup language mainly uses tags, which the starting mark looks
  4. like ``[xxx]`` and the ending mark looks like ``[/xxx]``. You can add an
  5. attribute to the starting mark to modify the tag's behaviour.
  6. There is a generic/quick ending mark which looks like ``[/]``.
  7. It cannot be used with all tags, so when it is used in the examples below,
  8. suppose you can use it, otherwise, it might not be possible (or not
  9. implemented yet).
  10. --------------
  11. Align the text
  12. --------------
  13. To align the text, you can use either ``[<alignment mode>]`` or
  14. ``[align=<alignment mode>]`` with any of the following modes:
  15. - ``left``: the text is left-aligned;
  16. - ``right``: the text is right-aligned;
  17. - ``center``: the text is aligned at the horizontal middle of the document;
  18. - ``justify``: the text is justified, i.e. the text spaces are optimized for
  19. the right'n'word to end at the right of the line.
  20. For example, to right-align some text, you could do something like this:
  21. .. code::
  22. [right]some text[/]
  23. ----------------
  24. Inserting titles
  25. ----------------
  26. Do you want to include titles or subtitles to your message, integrated with
  27. the website's design? Use the ``[title]`` and ``[subtitle]`` tags for that:
  28. .. code::
  29. [title]Just do it![/]
  30. [subtitle]Don't let your dreams be dreams![/]
  31. Notice that this tag cannot embed another tag.
  32. ----------------
  33. Styling the text
  34. ----------------
  35. You can add some basic text style by using the following tags:
  36. - ``[b]`` for **bold** text;
  37. - ``[i]`` for *italic* text;
  38. - ``[u]`` for underlined text;
  39. - ``[o]`` for overlined text;
  40. - ``[s]`` or ``[strike]`` for striked text.
  41. They can all be ended with the generic ending mark ``[/]``.
  42. ----------------------
  43. Changing the text font
  44. ----------------------
  45. You can change the font of the text by using the ``[font=xxx]`` (or ``[xxx]``
  46. directly, where ``xxx`` represents the font identifier) tag. The following
  47. fonts are available:
  48. - ``arial`` represents Arial;
  49. - ``comic`` represents Comic MS;
  50. - ``tahoma`` represents Tahoma;
  51. - ``courier`` represents Courier;
  52. - ``haettenschweiler`` represents Haettenschweiler;
  53. - ``mono`` and ``monospace`` represents the basic monospace font.
  54. They can be ended with the generic ending mark ``[/]`` as well.
  55. -----------------------
  56. Changing the text color
  57. -----------------------
  58. You can change the color of the text using the ``[color=xxx]`` (or ``[xxx]``
  59. directly for simple colors, where ``xxx`` represents the color) tag. This
  60. tag accepts several types of values:
  61. - simple color names (`inspired from CSS <CSS named colors_>`_) such as
  62. ``red``, ``blue``, ``green``, ``transparent``;
  63. - color hex codes using a hash (``#``) followed by hex digits, e.g.
  64. ``#01020F``, where the first group of hex digits represents the
  65. red component from 0 to 255, the second group of hex digits represents
  66. the green component from 0 to 255, and the third group of hex digits
  67. represents the blue component from 0 to 255.
  68. Incomplete composites will be filled by zero on the left (e.g. ``#0000F``
  69. is equivalent to ``#00000F``), invalid characters such as ``A`` will be
  70. replaced by 0s;
  71. - three hex digits codes using ``#`` followed by three hex digits, e.g.
  72. ``#123`` which will be translated to ``#112233``;
  73. - ``rgb(<red>, <green>, <blue>)``, where the red, green and blue components
  74. are represented using decimal digits and are between 0 and 255 included;
  75. - ``rgba(<red>, <green>, <blue>, <alpha>)``, where the red, green and blue
  76. components are expressed as said before and the alpha component is either
  77. expressed as a percentage (e.g. ``12.34%``) or as a proportion between
  78. ``0.0`` and ``1.0``;
  79. - ``hsl(<hue>, <saturation>, <light>)`` or
  80. ``hls(<hue>, <light>,<saturation>)``;
  81. - ``hsl(<hue>, <saturation>, <light>, <alpha>)`` or
  82. ``hls(<hue>, <light>, <saturation>, <alpha>)``;
  83. - ``hwb(<hue>, <white proportion>, <black proportion>)``.
  84. Here are some examples:
  85. .. code::
  86. [blue]I'm blue![/]
  87. [color=#ff69b4]That color is called “Cuisse de Nymphe émue”![/]
  88. [color=rgb(255, 255,255,0.4)]I'm black![/]
  89. [color=hsl(0,100%, 0.5)]I'm red![/]
  90. --------------------
  91. Inserting hyperlinks
  92. --------------------
  93. Creating hyperlinks on a bunch of text is possible through the ``[url]`` tag.
  94. The URL has to be either absolute, relative, or related to an anchor. It has
  95. to be passed to the tag either through the argument (which allows the content
  96. to be the displayed title of the link) or through the content if there is
  97. no argument. By default, if there is no content and an argument, the argument
  98. will be taken as the link title.
  99. Here are examples:
  100. .. code::
  101. [url]https://planet-casio.com[/]
  102. [url=https://planet-casio.com]Planète Casio[/]
  103. [url=/relative/url.html][/]
  104. For links to profiles, the ``[profil]`` and ``[profile]`` tags can be used.
  105. They take no attribute but take a content which is the user whose the profile
  106. is to be linked's name. For example:
  107. .. code::
  108. [profil]Cakeisalie5[/]
  109. For links to topics and tutorials, the ``[topic]`` and ``[tutorial]``
  110. tags can be used. They take no attribute but take a content which is the
  111. identifier of the topic or tutorial to which to link to.
  112. For example:
  113. .. code::
  114. [topic]234[/]
  115. [tutorial]32[/]
  116. For links to programs, the ``[program]`` and ``[prog]`` tags can be used.
  117. They take no attribute but take a content which is the identifier of the
  118. program to which to link to. For example:
  119. .. code::
  120. [program]3598[/program]
  121. ---------------
  122. Quoting someone
  123. ---------------
  124. To quote someone visually, you can use the ``[quote]`` tag, which takes the
  125. name of the person you're quoting as the attribute and the quote as the
  126. content. A quote can contain another one, of course. If there is no name,
  127. the display will just be generalistic.
  128. Here are examples:
  129. .. code::
  130. [quote]Someone said that.[/]
  131. [quote=Cakeisalie5]Ever realized that my name contained “Cake”?[/]
  132. -------------------------
  133. Spoilers/Content Warnings
  134. -------------------------
  135. To hide something behind a deliberate action of your user, usually to avoid
  136. hurting people or to hide the solution to a problem, you can use the
  137. ``[spoiler]`` tag.
  138. .. code::
  139. [spoiler]This is hidden![/]
  140. [spoiler=Uncover the dark secrets of the night]Boo![/]
  141. [spoiler=Uncover this!|Cover this quick!!]BOOO![/]
  142. ---------------
  143. Presenting code
  144. ---------------
  145. There are two code tags:
  146. - ``[code]``, which is supposed to be used as a block for multiline code or
  147. to isolate the code from the text;
  148. - ``[inlinecode]`` or the *backquotes* to include code in the text.
  149. For example:
  150. .. code::
  151. [code]Some multiline code, with [center]tags shown as they are[/center].
  152. Incredible, heh?[/code]
  153. [inlinecode]Some inline code.[/inlinecode]
  154. `Some more inline code.`
  155. ------------------
  156. Inserting an image
  157. ------------------
  158. In order to insert an image, you will have to use the ``[img]`` tag. It will
  159. make a new paragraph containing the image which the URL is given in the
  160. tag content. The tag can be bundled with some attributes, separated with
  161. the pipe (``|``) character:
  162. - ``<width>x<height>``: set the dimensions to the image. If the width isn't
  163. given (i.e. if this attribute starts with ``x``), the height will be set
  164. automatically. If the height isn't given (i.e. no ``x`` or nothing after
  165. the ``x``), the width will be set automatically;
  166. - ``left``, ``right``, ``center``: align the image accordingly;
  167. - ``float``: make the image float, i.e. let the text be where the image isn't.
  168. For example:
  169. .. code::
  170. [img=right|float|x24]https://example.org/image.jpg[/]
  171. is a right-aligned image, floating (which means text will be allowed on
  172. the left of the image), and with a height of 24 pixels and an automatic
  173. width.
  174. Planète Casio admins can use the ``[adimg]`` tag which is equivalent to the
  175. ``[img]`` tag but adds the special admin image folder prefix to the image
  176. URLs, so this is possible:
  177. .. code::
  178. [adimg]incredible.jpg[/]
  179. -----------------
  180. Inserting a video
  181. -----------------
  182. This BBcode translator has the ability to integrate videos from some online
  183. platforms into your message, as a block. To do this, you can use the
  184. ``[video]`` and ``[video tiny]`` tags. For example:
  185. .. code::
  186. [video]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
  187. [video tiny]https://www.youtube.com/watch?v=yhXpV8hRKxQ[/]
  188. ------------------------
  189. Inserting a progress bar
  190. ------------------------
  191. Do you want to present how your project is evolving using a simple graph,
  192. the progress bar? This is possible using the ``[progress]`` tag, which takes
  193. the percentage (between 0 and 100 included) of the advancement as its
  194. attribute. For example:
  195. .. code::
  196. [progress=50]Building a great wall…[/]
  197. [progress=100][/]
  198. ----------------------------
  199. Inserting labels and targets
  200. ----------------------------
  201. Is your message in several parts and you only want to link one without using
  202. an entire separate page for the section? This is the tag you might want
  203. to use. To link to a point in your message:
  204. - first, define the label using the ``[label]`` tag, with the name of the
  205. label as the attribute;
  206. - then link to the label using the ``[target]`` tag.
  207. You are not obliged to terminate the ``[label]`` tag (the original version of
  208. it didn't support the ``[label]`` tag termination, in fact). For example:
  209. .. code::
  210. [label=sometag][subtitle]Some chapter[/subtitle]
  211. ...
  212. [target=sometag]Go back to the beginning of the chapter[/]
  213. .. _CSS named colors: https://drafts.csswg.org/css-color/#named-colors