Page MenuHomePhabricator

Create a "Hello, World" Rosetta Stone for Multi-Language Support Tests
Closed, WontfixPublic

Description

Per discussions on IRC with @ajwillia.ms, the documentation should be built in order to support at least five languages: C, C++, JavaScript, Python, and C#.

Building on Nate Drake's draft "Hello, World" C example documentation, I propose the creation of two or more additional draft "Hello, World" documents using alternative languages from the above list and featuring the bare minimum of changes (i.e. duplicate the existing C version, then go through and change whatever needs to be changed for it to be a Python version, then do the same for JavaScript.)

Using these files we can then formulate and test an approach for the handling of language-specific documentation, from one of the following (or any other suggestion anyone has that could be better):

  • Separate each language out into its own namespace (the current approach, increases maintenance and risk of divergence);
  • Use a tabbed-code plugin to bring up only the user's required language (not portable, may not work for changes made outside code blocks);
  • Put no code in the documents themselves but have the code read in from external files (not portable, will not work for changes made outside code blocks);
  • Produce documentation in a single 'master' language then direct readers to appendices for alternative languages (unfriendly to those not using the 'master' language);
  • Produce 'master' documentation with all languages included then use an automated document generator to create language-specific documents in separate namespaces (reduces the maintenance and risk of divergence, but means the language-specific documentation will not be editable in DokuWiki as with the Eolian autodocs).

The production of multi-language versions of Nate's "Hello, World" documentation will be vital in figuring out which of the above approaches to take - or an alternative approach not yet considered, suggestions for which are very much welcomed.

ghalfacree updated the task description. (Show Details)Oct 25 2017, 9:20 AM
ghalfacree closed this task as Resolved.Oct 30 2017, 10:05 AM
ghalfacree claimed this task.

Multi-language support will be achieved by having language-specific sections, as per the documentation structure plan: https://phab.enlightenment.org/w/doc_system/doc_structure/ - which means there's no need to work on a Roseeta

ghalfacree reopened this task as Open.Oct 30 2017, 10:09 AM

Re-opening as per discussion with @ajwillia.ms on IRC.

cedric closed this task as Wontfix.Dec 1 2017, 4:40 AM

Closing it now that we have some tutorials and that it seems clearer that we will have per language tutorials