Overhauling user manual

sunderme commented 2 years ago

The user manual seems to be more and more outdated. I have started to convert the manual to markdown and reordered it. (https://github.com/texstudio-org/texstudio/blob/master/utilities/manual/usermanual_en.md) Help is welcome, especially for the parts which are annotated todo . Target audience are users who are getting started and are looking for new features or trying to solve issues.

sunderme commented 2 years ago

there are a few points i want to achieve and maybe someone can help.

TOC should be beside the text in html, similar to https://pandoc.org/MANUAL.html
tooltips on top of images would be great to allow context sensitive information.

octaeder commented 2 years ago

destroyed my bookmark chapter, please fix:

sunderme commented 2 years ago

https://github.com/texstudio-org/texstudio/pull/2607#issuecomment-1257010002 , furo looks interesting. For now the usermanual_en.md is written as markdown. Let's see what is the best way to get a html out of it.

octaeder commented 2 years ago

your images look quite oversized. Ex. quickstartwizard is 1050 pixels wide, more than half of a FullHD display. Image info shows 144dpi. It should be rendered at about 96dpi (67%).

dbitouze commented 2 years ago

#2607 (comment) , furo looks interesting. For now the usermanual_en.md is written as markdown. Let's see what is the best way to get a html out of it.

Here is a proof of concept with (a minimal configuration of) Sphinx-doc as documentation generator and usermanual_en.md as source file (as it is: could be improved):

for the HTML output (with Furo as theme): https://dbitouze.gitlab.io/texstudio-manual/usermanual_en.html
for the PDF output: texstudio.pdf

dbitouze commented 2 years ago

usermanual_en.md as source file (as it is: could be improved)

I meant, from the Sphinx-doc point of view.

I also forgot to give the link to the source: https://gitlab.com/dbitouze/texstudio-manual

sunderme commented 2 years ago

I tried to use sphinx here. Apparently it is a bit tricky on ubuntu (20.04) as the extensions are not present and it failed. I can get a very similar output with pandoc alone which is less complicated. So for now, I will generate the helpfile this way, but that does not mean we can't change it later as the source is the same anyway.

dbitouze commented 2 years ago

I tried to use sphinx here. Apparently it is a bit tricky on ubuntu (20.04) as the extensions are not present and it failed.

Here is a procedure that worked for me in a VM with Ubuntu 22.04:

sudo apt-get install python3-pip python3-dev python3-setuptools apache2 -y
pip3 install --upgrade pip
pip3 install sphinx
pip3 install myst_parser
pip3 install sphinx_comments
pip3 install sphinx_design
pip3 install sphinxext.opengraph
pip3 install furo
mkdir ~/tmp
cd ~/tmp
wget https://gitlab.com/dbitouze/texstudio-manual/-/archive/main/texstudio-manual-main.tar.bz2
tar xvfj texstudio-manual-main.tar.bz2
mkdir texstudio-manual
cd texstudio-manual
~/.local/bin/sphinx-quickstart # Answer `y` at the first question and whatever you want
                               # at the subsequent questions (the answers will be erased by the
                               # configuration file I provide).
mv -f ~/tmp/texstudio-manual-main/source/* source/
sed -E -i 's#sphinx-build#~/.local/bin/sphinx-build#g' Makefile
make html
xdg-open build/html/usermanual_en.html

octaeder commented 2 years ago

[ ] some images in chapter 1 show a terminal tab which is not present by default
[ ] maybe 1.1 should give hint that installing LaTeX should be done before starting TeXstudio (what happens when you proceed the other way round?)
[x] wrong image in section 1.2 (read the text),
[x] some of the text moved to 6.1, so same problem there (app image missing)
[x] Quick Start wizard shown in 1.3 is old while the one in 2.1.1 is new (not released change)
[x] last sentence of introduction to 5.8 not longer suitable since you (re-) moved description for the pdf-viewers

sunderme commented 2 years ago

for whatever reason, pip install failed here. But from what I see, it is not really necessary to run sphinx more than once. The only important part seem the template for pandoc and the css file (and js possibly). My current approach is an adaptation of https://github.com/Mushiyo/pandoc-toc-sidebar and this seems to be sufficient. With pandoc present, you only have to call convertToHTML.sh in texstudio/utilities/manual.

dbitouze commented 2 years ago

Here is a procedure that worked for me in a VM with Ubuntu 22.04:

I forgot the process for the PDF output format::

cd ~/tmp/texstudio-manual
make latexpdf
xdg-open build/latex/texstudio.pdf

dbitouze commented 2 years ago

My current approach is an adaptation of https://github.com/Mushiyo/pandoc-toc-sidebar and this seems to be sufficient.

But, this way, you cannot get PDF output format.

dbitouze commented 2 years ago

for whatever reason, pip install failed here.

Probably easy to fix.

sunderme commented 2 years ago

pandoc can deliver pdf as well (via latex) and it looks okay. The important part is to have a markdown source file, that we can transform in all outputs, one way or another. For html output, I would prefer a pandoc only approach as set-up seems to be easy enough on any system. You can still let run sphinx for a more fancy output.

sunderme commented 2 years ago

pip upgrade did the trick

sunderme commented 2 years ago

@dbitouze building the html locally, there is a second toc to the right. That is actually quite useful as it is more detailed than the one on the left. However it does not scroll with the text, i.e. when the entry is outside of the current view, it does not scroll there. This may or may not be desirable ? Anyway, the search box seems to be pretty useless for single page document. The comment function should not be there as it links to an external site. Otherwise looks quite nice.

dbitouze commented 2 years ago

@dbitouze building the html locally, there is a second toc to the right.

Interestingly, my local build doesn't provide such a local ToC but, indeed, there are provided for another project (a French LaTeX FAQ), e.g. https://dbitouze.gitlab.io/test-faq-fr/3_composition/tableaux/tableau_sur_plusieurs_pages.html

That is actually quite useful as it is more detailed than the one on the left. However it does not scroll with the text, i.e. when the entry is outside of the current view, it does not scroll there. This may or may not be desirable ?

In the link above, you can see that the local ToC does scroll with the text.

Anyway, the search box seems to be pretty useless for single page document.

There could be two versions of the manual: one with a single page embedded with TXS, and another one, online, with several pages (more friendly IMO).

The comment function should not be there as it links to an external site.

Again, could be useful for an online manual.

Otherwise looks quite nice.

OK.

sunderme commented 2 years ago

I have split the help file and put everything together in https://github.com/sunderme/texstudio/tree/manual Maybe you can have a look ?

sunderme commented 2 years ago

direct link to the result: https://htmlpreview.github.io/?https://github.com/sunderme/texstudio/manual/utilities/manual/build/html/getting_started.html

sunderme commented 2 years ago

I have put it on github pages to test: https://sunderme.github.io/getting_started.html

dbitouze commented 2 years ago

I have put it on github pages to test: https://sunderme.github.io/getting_started.html

Very nice, thanks!

Some minor remarks after a quick overview:

some commands are not entered as code (\hline, %\s?[A-Z][A-Z_-]+, etc.),
keyboard keys should be harmonized and displayed with a nice and special style (e.g. “Ctrl+Shift+I” → Ctrl+Shift+I, if not Ctrl+⇧+I).

dbitouze commented 2 years ago

IMO, sphinx-comments is still useful since, used with e.g. https://web.hypothes.is/:

the visitors are then able to put comments (that might be helpful for improving the manual) without the necessity to open an issue (and then to have a GitHub account),
it can be used by the visitors just as comments (and global bookmarks over the Internet) for themselves.

sunderme commented 2 years ago

the whole manual is static with local resources, only the comments would break that. Especially as the manual is also installed locally on the user's computers.

dbitouze commented 2 years ago

the whole manual is static with local resources, only the comments would break that.

Is it a big deal?

Especially as the manual is also installed locally on the user's computers.

This would concern only the online version of the manual.

sunderme commented 2 years ago

there is no "online" version of the manual, it is the same on the computer and on pages. In Germany, there was a successful law-suit that loading google fonts from google in the webpage was a violation of privacy, so I stay away from that as much as possible.

dbitouze commented 2 years ago

In Germany, there was a successful law-suit that loading google fonts from google in the webpage was a violation of privacy, so I stay away from that as much as possible.

AFAICS, no Google Font here.

octaeder commented 2 years ago

[x] typo in "The result is in ./build/html/ , getiting_started.html as entry point." of file Readme.md

octaeder commented 2 years ago

[x] Text and command examples in set-up for external viewers are broken: Many new brackets [ or ], or parts of command lost (s. okular, Foxit Reader has add. slash).

octaeder commented 2 years ago

Remarks on chapter Configuring TeXstudio:

[x] spellchecker, thesaurus, and grammar are no longer configured under General, move it to Grammar. The syntax checker is configured under Completion.
[x] As the group is called Menus the section should be Configuring the Menus. Seems to be reasonable since configuration of all menus is possible, not only math and latex.
[x] As the group is called Toolbars the section should be Configuring the Toolbars. Seems to be reasonable since configuration of all toolbars is possible, not only for custom toolbar.
[x] As the group is called SNV/GIT the section should be Configuring SVN/GIT.
[x] There is a backslash after The internal pdf viewer also accepts the following options (txs:///internal-pdf-viewer) to modify its behaviour:

Chapter Advanced features:

[x] There is a backslash at the end of The “run script” button directly executes a script in the editor for testing.
[x] and at the end of Additionally the following special trigger terms (without parentheses) can be used to execute the script when the corresponding event occurs:

Chapter Background information:

[x] There is a backslach after [#classification] (s. cwl file format).
[x] There is a backslash after Examples: (s. between the two tables in classification format).

octaeder commented 2 years ago

[x] The toolbars can be hidden by a right click on an empty space in the toolbar area. It is unnecessary to target on empty space and could be difficult. Even this is possible (right click on the dropdown):
[x] Adapting the main GUI about toolbars: They can be moved by dragging the handler on the left-hand side. So the user might wonder why this is not true for the central bar. Cool, if you could change the behavior for it, otherwise you could give it a small note. Note: central toolbar has no handler, so it is not movable.
[ ] This is not a current image as you can see here:
[x] OpenOffice link (http://extensions.openoffice.org/de/search?f[0]=field_project_tags%3A157) is outdated. Seems to run but should be https.
[x] LibreOffice link (https://extensions.libreoffice.org/extensions?getCategories=Dictionary&getCompatibility=any) seems to be outdated, jumps to https://extensions.libreoffice.org/?Tag%5B0%5D=50&q=.
[x] Changing shortcuts is a little bit different for Editor/Basic Key Mapping: Only Current Shortcut can be changed, no Additional Shortcut is possible.

octaeder commented 2 years ago

Chapter Editing a Tex Document, section Formatting your text right at the beginning:

[x] toolbar in two words found
[x] the image of the Format toolbar is outdated. Changing text size is done in the (horizontal) Format toolbar (s. getting started). The others can be found in the (vertical) Central toolbar. Btw. to be consistent, it should be Central in the image (chapter getting started) as you used Tools, Format, Table.
[x] Note beginning with A selected text can be directly framed by certain environments. states This option is available for all the environments indicated by “[selection]” in the “LaTeX” menu. But nothing like [selection] can be found in the LaTex menu.
[x] Image of the Quick Tabular wizard is outdated. Btw. some of the wizards can be closed with ESC, others not.
[x] Image of the Insert Graphics wizard is outdated. So it shows something interesting with respect to PR #2609: The second option was part of the frame (marked here with red lines) surrounding the options for caption, label, and position. The first two options are aligned. So I believe the PR was a fix not a GUI change.
[x] Section Cross References and notes shows **Additional option:** right after the image. Seems to be a mark down.
[x] Chapter Inserting math formula shows math symbols in the Math toolbar, but these are located in the Central toolbar these days.
[x] Another backslash: The completer has several operation modes which are shown in the tabs below the command list.\
[x] Please add to the Auto Completion section that switching operation mode is done with SHIFT+SPACE.

octaeder commented 2 years ago

[x] typo in The changes is perofrmed immediately (Configuring TeXstudio/Configuring GUI scaling)

octaeder commented 2 years ago

[ ] "Welcome to TeXstudio Manual’s documentation": Has this a special meaning? I mean manual and documentation.

@sunderm I still wonder if the title should rather be "Welcome to TeXstudio's Manual" or "Welcome to TeXstudio's documentation". Current title seems to be a mixture of both. Is it intended?

octaeder commented 1 year ago

[x] typo in available as shortcurs (Editing a TeX document/Formatting your text)
[x] Editing a TeX document/Inserting a table/Manipulating tables contains a short paragraph about block cursors. But now there is a new section Block cursor in Special Commands. Maybe the first one should have a link to the second or this should be consolidated.
[x] Last sentence in Block cursor is By clicking Ctrl+Shift+Alt+left click a block from the current cursor to the mouse position is selected. But Ctrl+Shift+left click is sufficient for this and much easier to press with your left hand :-)
[x] Please add that you can create a column of cursors with Ctrl+Alt+CursorUp/Down.
[x] Please add that all cursors can be moved with CursorLeft/Right/Up/Down at once.

octaeder commented 1 year ago

[ ] In Editing a TeX document/Inserting a table/Manipulating tables contains a short paragraph about block cursors. It says Press Ctrl+Alt and drag the cursor with the mouse. But the keys are Ctrl+Shift as pointed out in special commands Block cursor. Comment: PR #2619 2619 rejected.

octaeder commented 1 year ago

[x] The image showing the context menu of the inline preview shows Clear In...e Preview instead of
[ ] The preview pane and it's context menu could be described/presented.

octaeder commented 1 year ago

[x] In Configuring TeXstudio/Configuring the spell checker, wrong wording in on windows a large number is languages is provided. Suggesting "of" replacing first "is".
[x] In the same paragraph we find A particularly convenient way to get additional dictionaries is downloading a dictionary extension of http://wiki.services.openoffice.org/wiki/Dictionaries or LibreOffice. For the first link I feel it's not nice to use a different link under the hood. Both links should be those of PR #2615 , s. my post above from september 29th at 12:24 am.

octaeder commented 1 year ago

add to previous post:

[x] wrong wording in Linux distributions usually over a wide range of hunspell dictionaries as well which can be used. Suggesting "offer" replacing "over".

octaeder commented 1 year ago

[x] In Configuring the grammar checker, wrong wording in which need to be provided in the “Wodlist Directory”.

octaeder commented 1 year ago

[ ] I wonder if this is a current image (compile_toolbar.png, s. Compiling a document):

The stop symbol is not a square, but it is in the images of chapter Getting started.

[ ] analog with viewbutton.png (s. Viewing a document)

sunderme commented 1 year ago

in my opinion, the main update work is done.

octaeder commented 1 year ago

[x] The texstudio.org page still shows user manual with link to old manual. (s. below)

octaeder commented 1 year ago

@sunderme Which of the following changes/additions to the manual do you (not) want to have? These are from my task lists above. Please leave comments:

As the group is called Menus the section should be Configuring the Menus. Seems to be reasonable since configuration of all menus is possible, not only math and latex.
As the group is called Toolbars the section should be Configuring the Toolbars. Seems to be reasonable since configuration of all toolbars is possible, not only for custom toolbar.
Add a note that changing shortcuts is a little bit different for Editor/Basic Key Mapping: Only Current Shortcut can be changed, no Additional Shortcut is possible.

And what about this? The texstudio.org page still shows user manual with link to old manual.

Thx

sunderme commented 1 year ago

@sunderme Which of the following changes/additions to the manual do you (not) want to have? These are from my task lists above. Please leave comments:
1. As the group is called _Menus_ the section should be _Configuring the Menus_. Seems to be reasonable since configuration of all menus is possible, not only math and latex.

2. As the group is called _Toolbars_ the section should be _Configuring the Toolbars_. Seems to be reasonable since configuration of all toolbars is possible, not only for custom toolbar.

3. Add a note that changing shortcuts is a little bit different for Editor/Basic Key Mapping: Only _Current Shortcut_ can be changed, no _Additional Shortcut_ is possible.
And what about this? The texstudio.org page still shows user manual with link to old manual.

Thx

I have implemented the changes. texstudio.org will be updated with the next release.

octaeder commented 1 year ago

[x] One "be" to much in

The appropriate item can be be directly edited by double-clicking on them.

(s. Configuring the Menu).
[x] You typically write toolbar in one word, for example in the heading (s. parentheses at the end here) or in the first sentence, but not in "user tool bar":

TeXstudio can adapt all toolbars with actions from the menus. A “user tool bar” is empty by default

(s. Configuring the Toolbar). Is it intended?

octaeder commented 1 year ago

s. here

[x] There should be no double quote in: In advanced mode, you can reference it using txs:///"\<command id>
[x] Should be "them": Do not use then at Options -> Commands.

octaeder commented 1 year ago

@sunderme Shouldn't there be a md file for each html file, as it is for configuration.html? 8066ab7075c7a6205dcacc113974b092eea0a799

grafik

I think that these files will be overwritten when the manual is generated the next time.

octaeder commented 1 year ago

@sunderme In chapter Editing a TeX Document -> Special Commands -> Rename Environment:

[x] it may worth noting that one can circumvent waiting for the mirror cursor by double-clicking the environment name. This will immediately activate the mirror cursor. As a side effect, the name is selected and you can enter a new name. As an example: change equation to aligned.

dbitouze commented 1 year ago

there is no "online" version of the manual, it is the same on the computer and on pages. In Germany, there was a successful law-suit that loading google fonts from google in the webpage was a violation of privacy, so I stay away from that as much as possible.

A drawback of not providing an online manual is that the one coming with TXS has a search box which doesn't work.

And TXS would be I guess the single software in the world that doesn't provide an online version of its manual...

sunderme commented 1 year ago

there is an online version of the manual (https://texstudio-org.github.io/getting_started.html), it simply is not the only one.

texstudio-org / texstudio

Overhauling user manual #2608