OnlineScholar

Frequently Asked Questions (FAQ) about OnlineScholar

1.1. What is the final resulting URL for my pages

In the editor, press Publish then Live and you will see the URL of that live page.

You can ignore the portion after the question mark (?), it is just a random number that clears your browser’s cache so you see the latest results.

1.2. Why don’t you use a WYSIWYG editor?

We looked but have not yet, essentially for two reasons:

  1. We haven’t found one that meets the requirements of both supporting ASCIIdoc and working reliably. (For the technical answer, to do a good rich text editor one has to totally re-implement the DOM as any attempt to simple manipulate the DOM dynamically usually fails, a symptom of most early public attempts to implement rich tech editors.)

  2. It’s easy to miss the whole intent of this system: giving a solution to people who use and like LaTeX-styled control. WYSIWYG is oriented for the MS-Word-loving population and they may well prefer it and tools oriented that way, but most STEM academics are not well served by those tools. In fact, most who have written a book or a lot of documentation in a big project with images and complex information will have found they outgrown most WYSIWYG tools quickly after starting down that path.

1.3. Why do some page links not work in the Preview features

Most commercial sites like Google and many content management systems prevent being diplayed inside a container (an _iframe specifically). To test them, go to the Live view of the web page and test your links.

1.4. How do I make relative links?

To link to files in your project or personal space, like to filename.html

example
link:index.html[home]

1.5. Can I edit offline in a nicer editor

Certainly. You can cut and paste from any text editor. The easiest strategy may be to download Asciidoctor which is freely availale for WIndows, Macintoshes and Linux. It is approximately 99% compatible with the features of OnlineScholar.

1.6. How do I make external links

Specify the full URL, including https://

example
link:https://google.com[home]

1.7. How to I restrict access to my pages?

  1. Until you hit publish, nothing is world visible

  2. If you wish, you can restrict access to published data by selecting manage from the project page and select Intranet as the audience. The default option is Public which is availble offsite.

1.8. How do I make ordered lists?

Simple ordered lists are made with dot

example
My list

. item one
. item two

If you wish to pick up at a certain index, eg. 4, add something like the following above your next period.

  [start=4]

If you wish to number sections with headings, add to the top:

:sectnums:

Google asciidoc sectnums for more information.

1.9. What is the AI feature?

After you create your document, simply press the AI button to get a list of suggestions for possibly improving the text. The AI process usually takes a few seconds, but can take longer if multiple people are requesting it at the same time. As with all generative AI, results will vary in usefulness.

Note AI skips all math equations entered with asciimath. _

1.10. How do I offer BibTex or other files for download

See Attaching Files

1.11. What is the Exit Strategy

Tip
 Every technology has a lifetime after which it is less compelling or even terminated for some reason. Before adopting any technology you should always determine what the risks are and what options will exist to recover your data investment. If not, you will be locked in or lose use of your data over time.

Given that reality, what options exist, both for individuals (who may change organizations) and organizations themselves.

The truth is that there are excellent options available today for extending the life of this data. OnlineScholar integrates ASCIIdoc with access controls, publishing, user interface, etc. But the data is not in proprietary formats.

OnlineScholar is based only on open technologies first conceived in 2002 and becoming widely adopted. ASCIIdoc is in the process of becoming an open standard with a standards body working group looking at fully describing the standard, and there is an open source reference implementation which is used by OpenScholar, AsciiDoctor and various other products both open and closed source. It is written in Ruby but also cross compiled to JavaScript and Java. You can import files from OnlineScholar and use them immediatley with any of these tools.

Since it is an open standard solution, people have already started making converstion tools, such as pandoc which can now convert to AsciiDoc, and hopefully will soon be able to convert from it to other formats. Also, ASCIIdoctor can convert ASCIIdoc to various formats including LaTex.

There are numerous solutions described on the web for converting from ASCIIdoc to formats like Word, Latex, etc.