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

Add subsubsection in docs. #1030

Open
rocky opened this issue Apr 4, 2024 · 6 comments
Open

Add subsubsection in docs. #1030

rocky opened this issue Apr 4, 2024 · 6 comments

Comments

@rocky
Copy link
Member

rocky commented Apr 4, 2024

Mathics3 modules in documentation are shifted down a level. In order to support "Guide" sections in Mathics3 modules, we would need to add a subsubsection support in LaTeX.

Consider https://reference.wolfram.com/language/guide/LinguisticData.html

linguistic-data

We currently can't capture this structure in our documents because WordTranslation, Alphabet, LanguageIdentify etc. are at the subsubsection level.

Because right now document structure follows module structure, we also can't create a module in the Mathics3 Module for "Languages and Translation" and "Textual Analysis" and have its appear in the LaTeX doc.

Two other things.

Having subsubsections might be also useful outside of Mathics3 Modules.

Note that in Wolfram documentation Symbols are at multiple levels: WordData is at a different level than WordTranslation. If you want to think of there being and "anonymous" section or subsection", note that there is more than one of these anonymous (sub)sections

@mmatera
Copy link
Contributor

mmatera commented Apr 4, 2024

@rocky, actually, we still have "Subsections". What I have changed is that "GuideSections" are Sections, so they contain "Subsections" instead of sections.
Symbols in pymathics.natlang.translation should be accommodated in the current "mathics-code/master" as Subsection of a GuideSection "Translation" inside the chapter "Natural Language" of the "Mathics Modules" Part.

I didn't check this package (I just had installed Pymathics.Graph when I run the tests) but it should work exactly the same. I will check what happens with natlang during the weekend.

@mmatera
Copy link
Contributor

mmatera commented Apr 4, 2024

Regarding this:

We currently can't capture this structure in our documents because WordTranslation, Alphabet, LanguageIdentify etc. are at the subsubsection level.

These elements are shown different in the documentation because they are not considered "Built-in Symbols" but "Entities":

image

In the online documentation there are no chapters/sections/subsections: just different kind of webpages ("Built-in refereces", "Guide Sections", "Tutorials", and "Entities").

@rocky
Copy link
Member Author

rocky commented Apr 4, 2024

From a code organization standpoint, it would be good to start supporting a format like that used in https://github.com/Mathics3/pymathics-natlang/pull/19/files . What you want to call the levels of the hierarchy in the LaTeX doc is up for discussion. However in the LaTeX markup, the nesting level is "subsubsection."

@mmatera
Copy link
Contributor

mmatera commented Apr 4, 2024

OK. My proposal for this would be to have three guides in the "Natural Language" chapter:

  • Linguistic Data: Include (as a documentation entry, an explanation of the content, and a list)
  • Languages & Translations: contains the symbols in lang_trans.py as subsections
  • Translation: contains the symbols in lang_trans.py as subsections.

@rocky
Copy link
Member Author

rocky commented Apr 4, 2024

OK. My proposal for this would be to have three guides in the "Natural Language" chapter:

  • Linguistic Data: Include (as a documentation entry, an explanation of the content, and a list)
  • Languages & Translations: contains the symbols in lang_trans.py as subsections
  • Translation: contains the symbols in lang_trans.py as subsections.

Yes, that makes sense. The problem of this issue/feature is that right now we can't extract docs for the lowest level.

@mmatera
Copy link
Contributor

mmatera commented Apr 4, 2024

This is how Natlang looks (from its master branch) when I remove the other parts and chapters from documentation.tex:

image

During the weekend I will try to adjust this.

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

No branches or pull requests

2 participants