SCDoc improvements: 3. Some HTML tags are enabled. #6265
Conversation
…adability of rendered HTML Some HTML tags are enabled. "\n" is added to some tags to improve the readability of rendered HTML.
typo correction & removing unnecessary part
to place image with resize attribute
JordanHendersonMusic
added
the
comp: SCDoc
Internal and External links for iframe, audio, video and image now work
more examples and typo correction
|
updated again (deleted previous ones) Converted PDF from the corresponding reference in SCDoc included in this PR: |
|
I really appreciate the effort here and I see similarities to your proposed #6304 , but using replace to replace generated SCDoc HTML rendered code seems a hacky way of doing it as in this case we work against the output of SCDoc instead of telling it to "ignore" it. For example, Maybe there should be a focus on how to extend the SCDoc syntax to include a So, instead of working against the SCdoc generator, we can just work with it :) The definition of the SCdoc syntax is stated here which are used by Bison to generate a parser, see https://www.oreilly.com/library/view/flex-bison/9780596805418/ch01.html I think it should be feasible to include a new tag here, if you are interested in this we can take a look at this together, but currently the |
I thought about it today about an HTML:: tag that bypasses the renderer. It's an idea. |
Wow, I think it can simplify a lot of things! I really like it!
I have modified the files you refer to several times over the past year to implement Recently @smoge also recommended learning Bison and Flex... In between
OK! Modifying these files without exact knowledge is the reason for non-success. After I finish some urgent personal stuff, I will have a look at it.
I do not know what @smoge @capital-G |
|
@capital-G
|
|
It was a minor deprecation and easily fixable with Also, the commented line that compiles with gcc, works with a minor change. I had heard about this "breakage" before. But it does not seem to be the case. It's all right. |
|
@smoge @capital-G Here I have a new question. The followings for example seems not so fun to typing:
etc... I think it would be better to make a poll for the new modal tags.
I also would like to have a tag for table with I think @capital-G would wish some modal tags related to this.... |
The followings seem to be better:
Also:
|
|
I think we should limit this more towards a We could nonetheless include something like admonitions in myst or rst with an either limited or open set of possible classes. Something like would then be converted to <div class="scdoc-context math">
\int_0^\inf = \sin(x)~dx
</div>This makes it possible and very easy to edit such divs via JS or CSS and adjust/modify their style or content. Edit: To include arbitrary HTML content (this should be limited to HTML exclusive features such as embedding a video via iframes etc!) we could also add which would be simply forwarded/passed as <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ?si=WEomThZlWcYABnhC" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> |
|
Yes, let's follow the KISS principle. Let's add one or two tokens to the grammar, allowing more expressivity on the SCLang side. It will be better for future ideas and adaptations. Bison works just fine; I don't think it's 'archaic. ' It's a good tool. But grammars are a hard part of programming. Changes will always be more complicated. |
Yes, these are good! I already use HTML in SCDoc using the SCHTMLRenderer in this PR. There is a problem: by using HTML I should type in too much code to use Thus, we need the following modal tags:
The following PDF is a guide to all these features. Advanced SCDoc features _ SuperCollider 3.14.0-dev Help.pdf Is there anything I have missed? |
|
As mentioned above, I personally would strongly avoid any HTML beyond an By implementing a context (represented by wrapping the content inside a div that has a class as an attribute), it is possible to implement most of what you ask for. In general, I don't think that development efforts within SuperCollider are best spent on making SCDoc equal to other documentation or typesetting tools. If the community agrees that there is an urgency to include such features, then we should replace SCDoc with a tool dedicated to documentation like doxygen. |
I would like to mention that the community here are all experts in using SC and many of them are professional level programmers. They are not so dependent on the SuperCollider help document as they often understand just by looking at the implementation of the methods. However, my recent PRs are for my students who are outside the community. They are studying various subjects, are not musicians (I used to teach musicians, mainly composers, but not anymore) and are learning Audacity, Reaper and programming with SC for the first time in their lives. I do not use PDF or other tools to present code because some characters can be converted, so errors can occur when evaluating pasted code. I mainly use SCD files and my own tutorials in Korean written in SCDoc. SCD files are good for code, but not good for writing explanations as comments. SCDoc is good for linking the help documents and other help documents. The advantage of using SCDoc is that you can embed images. However, it is not very eye-friendly and its readability needs to be improved by adjusting the lead (spacing between lines), table width, line width between items, etc. The current fonts are also not very good for Korean. The use of the online documentation system is also very limited. There are computers with wired internet in the lecture room, but many students use their own laptops with Wi-Fi, but the Wi-Fi connection in the room is very unstable. I do not think there is an urgent need to implement such features for the community. However, I think it would not be a bad idea to start a poll to replace SCDoc with Oxygen. What do you think? If I make a poll, it will be ridiculous because I am not competent to replace SCDoc with Oxygeon. Or would it be better to close all my recent PRs related to this? (added:) |
|
I have updated #6266. The subsubsection now seems to be implemented correctly. |
I suppose you mean Doxygen? I think the recent PRs showed that there is still interest in SCDoc and we will also hopefully find a way to have create a way to improve it over time, but please be aware that SCDoc will never become a perfect typesetting tool as this is out of scope. (BTW, doxygen is also not a typesetting tool^^) Maybe a bit OT but if you are interested in writing course material I can maybe recommend a tool I wrote https://github.com/capital-G/sc_kernel which allows you to write Jupyter Notebooks with sclang. An example of this can be found The Problem in generalI think the DOM structure of the SCDocs HTML could be improved, as it is currently almost impossible to get hold of specific sections of a document via JS and CSS and adjust their style, because the DOM is essentially flat (and not deterministic) rather than nested within divs which create namespaces.
Normally every kind of section and element (e.g. a paragraph) should be nested with a div. But instead of going for such a big step I think it is best to implement something less drastic and would be useful even even if we have a proper nested DOM by allowing to create a context wrapper explicitly. PropositionContextI think #6265 (comment) already states how admonitions work within MyST/RST and this could be mimiced to create a context syntax within SCDoc. Something like should then result in Via .foo {
background-color: red;
}
.bar {
font-weight: bold;
}The set of global classes could then be discussed in an atomic basis. If you could extend the SCDoc parser to include the parsing of the context including classes like above it would be really great!! Maybe this could also allow to enter raw HTML for elements such as iframe via js // pseudo-code
for (let element of document.getElementsByClassName("raw-html")) {
const text = element.textContent;
element.innerHTML = element.textContent;
}Maybe there could be a syntax to create an inline-context via span classes, but I think this should be something for a 2nd PR. |
|
@capital-G Do I need to add the modal tag Why have I tried to improve SCDoc?
Adding the modal tag
Yes, it was a typo. Sorry! From my experience,
I am already familiar with your great tool and I like to use it. However, more than 90% of my students use Windows and very few of them use MacOS. In 10 years of teaching experience, I only meet 1 or 2 students who use Linux. So I cannot use your wonderful tool with my students. I think that a teacher and his students should use the same tool to avoid many technical problems. |
writing style change of the method added in this PR
This pull request enables you to incorporate HTML tags in order to enhance the appearance of the rendered HTML in both the web browser and SC Help Browser. Additionally, "\n" has been added to certain tags to make the rendered HTML more readable when viewed in a text editor.
Purpose and Motivation
While working on writing educational material using SCdoc, I encountered the need to use HTML tags in order to improve the readability of the printed SCDoc. I used these tags to add empty lines and control line height, and so on.
Some opinions have already been expressed in PRs #6260 and #6263. I am aware that some believe I may be doing things incorrectly. However, I am doing this in order to complete the task of dividing PR #6254.
This is a revised PR that addresses the relevant part of PR #6254. I plan to keep this PR open for several weeks to gather more feedback on my work.
Types of changes
To-do list