textout/README.rst

Planète Casio's textout() BBcode markup language translator
===========================================================

This module contains a BBcode to HTML translator for
`Planète Casio`_. For more information, read the
documentation accessible on `the official website`_.

.. warning::

	If you are accessing this repository from another forge (such as
	`Planète Casio's forge <https://gitea.planet-casio.com/cake/textout>`_),
	keep in mind that it is only a mirror and that the real repository
	is located `in my forge <https://forge.touhey.org/pc/textout.git>`_
	for now.

For example, if we want to translate some basic multi-block text to HTML:

.. code-block:: python

	from textoutpc import tohtml

	text = """[img=center]https://www.planet-casio.com/skins/bootstrap/img/default/logo.png[/img]

		Hello [color=R10]world[/color]!
		[ul]
			[*]This module is made by [url=https://thomas.touhey.fr/]Thomas Touhey[/url]!
			[*]Use `.tohtml()` to translate magically to HTML!
		[/]
	"""

	print(tohtml(text))

What is left to do for the next release
---------------------------------------

- Fix the not-passing unit test (``[color=blue]oh[youtube]h4WLX8hfpJw``).
- Produce a test stylesheet for demonstration purposes.
- Manage lightscript (or even markdown?) as output languages;
- Check where the errors are to display them to the user:

  * Count character offset, line number and column number in the lexer;
  * Produce readable exceptions;
  * Make a clean interface to transmit them;
- Check why exceptions on raw tags effectively escape the content, as it
  shouldn't…?
- Look for security flaws (we really don't want stored XSS flaws!).
- Implement match names (such as ``\[\*+\]`` for lists).
- Manage keywords with tags such as ``[tag key=value other="something else"]``.

.. _Planète Casio: https://www.planet-casio.com/
.. _the official website: https://textout.touhey.pro/