Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Minimize markup in variand and field descriptions. #7

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

aantron
Copy link
Contributor

@aantron aantron commented Oct 5, 2016

ocsigen.org's styles and parser currently assume that variand and field descriptions are simple preformatted comment strings. Meanwhile, wikidoc, like ocamldoc, expects the descriptions to be table cells with full documentation styling and block content.

This commit changes wikidoc to output the descriptions as text close to what is written in the source code, inserting much less markup.

I inspected the new output, and it looks correct up to my understanding of Wiki Creole and Ocsigen's extensions. I haven't tested final display on ocisgen.org.

I think the "right way" to fix this is to change the style and layout on ocsigen.org to allow block content in variand info, like ocamldoc does. However, that seems like an involved project that I'm not ready to do right now. Perhaps that can be done at a later date.

In the meantime, this helps to fix ocsigen/ocsigen.org-deprecated#19. To complete the fix, I will also remove ocamldoc markup from variands in lwt_unix.mli.

ocsigen.org's styles and parser currently assume that variand and field
descriptions are simple preformatted comment strings. Meanwhile,
wikidoc, like ocamldoc, expects the descriptions to be table cells with
full documentation styling and block content.

This commit changes wikidoc to output the descriptions as text close to
what is written in the source code, inserting much less markup.
@Drup
Copy link
Member

Drup commented Oct 6, 2016

This looks good to me, but I certainly don't know enough of wikidoc's internals to be confident this patch is correct.

Ideally I would like to be able to test with ocsigen.org/ocsimore, but that's a bit delicate.

@aantron
Copy link
Contributor Author

aantron commented Oct 6, 2016

I can try setting up a local ocsigen.org for testing, following the instructions in its README, but probably early next week.

@aantron aantron mentioned this pull request Dec 9, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Have a blessed CI script for uploading dev documentation.
2 participants