search

cyjoelchen / php-sweph

PHP Extension for Swiss Ephemeris
Other
63 stars 29 forks source link

Experimental doc .md files #63

Closed aloistr closed 3 years ago

aloistr commented 3 years ago

In branch documentation, ./sweph/doc I am experimenting with .md files created via pandoc -f docx -t markdown from the original Swisseph docx files. The results need manual work, for tabular data elements It is an experiment, into which I can only invest minimal time. I want to find out whether we should move from Word to markdown as fundamental maintenance firmat.

kevindecapite commented 3 years ago

I want to find out whether we should move from Word to markdown as fundamental maintenance firmat.

Do you mean for the main SE library? I would vote 100% yes to use markdown, but that would be a big endeavor to convert it all to that format. The advantages are many, however:

Sample Table

| House | Chart A             | Chart B             | Midpoint               |
| ----- | ------------------- | ------------------- | ---------------------- |
| 1st   | 19° Aquarius    | 13° Virgo       | __1° Sagittarius__ |
| 2nd   | 27° Aries       | 8° Libra        | __17° Cancer__     |
| 3rd   | 27° Taurus      | 7° Scorpio      | __17° Leo__        |
| 4th   | 16° Gemini      | 11° Sagittarius | __13° Virgo__      |
| 5th   | 1° Cancer       | 15° Capricorn   | __8° Libra__       |
| 6th   | 18° Cancer      | 16° Aquarius    | __2° Taurus__      |
| 7th   | 19° Leo         | 13° Pisces      | __1° Gemini__      |
| 8th   | 27° Libra       | 8° Aries        | __17° Capricorn__  |
| 9th   | 27° Scorpio     | 7° Taurus       | __17° Aquarius__   |
| 10th  | 16° Sagittarius | 11° Gemini      | __13° Pisces__     |
| 11th  | 1° Capricorn    | 15° Cancer      | __8° Aries__       |
| 12th  | 18° Capricorn   | 16° Leo         | __2° Scorpio__     |

That table was copy-pasted from the documentation I'm creating for my software: https://docs.lunaastrology.com/interact/composite-charts/#select-the-midpoint-base

In fact, that documentation is 100% markdown, powered by this free tool: https://squidfunk.github.io/mkdocs-material/

It is also hosted on Github pages.

astrorigin commented 3 years ago

I had planned to transfer a large part of the swisseph documentation into reStructuredText format (rst), to use with my software (using Sphinx). RST is generally better suited than markdown for technical documentation, and is supported by Github. If interested, I could go ahead and do that for the C API.

aloistr commented 3 years ago

I looked into rst and Sphinx. For my modest purposes, I think md (Markdown) is preferable. Its syntax is simpler, and it is sufficient. It seems to have simple markup cide to get for example blocks of C code or Perl code shown with syntax highlighting. In branch documentation, directory sweph/doc are sample .md files which I have begun editing a bit. Look in swephprg.md at the swemini.c sample code near the top, or in swisseph.md at the table of ephemeris files.

For me at Astrodienst it is also important that we have a lot of internal memos created since 1987, which are our continuous inhouse documentation. They are pure text, we had already gwo years ago discussed internally to move to markdown.

A single consistent format method is desirable for us.

md can also be used for Perl code highlighting with the ```perl directive. rst and Sphinx lack a Perl extension.

Because Astrodienst continues to remain Perl based, this is a relevant point for us.

astrorigin commented 3 years ago

I've checked and Sphinx supports Perl syntax-highlighting. https://pygments.org/languages/

(Perl documentation is probably usually served with perldoc/pod anyway)

aloistr commented 3 years ago

I have decided the issue. At Astrodienst, we move to Markdown (Github flavour) for future maintenance of the Swiss Ephemeris documention. The conversion is in progress, I do the work with the Typora editor on a Mac, with assistance from vi for conversion of existing tables.