Rewrite documentation

[ra3xdh]

The documentation on the https://qucs-s-help.readthedocs.io/ is totally outdated now and doesn't reflect the latest application state. This manual need to be 100% rewritten. I am planning to remove the readthedocs repository and replace it by new reference guide. In the long perspective I am planning to supply offline PDF documentation with the release version of the Qucs-S, because readthedocs has limitation on the file size. The documentation must be hosted in a separate repository. This repository must not be integrated in a main source tree.

I have drafted a contents of the reference guide here: https://github.com/ra3xdh/qucs_s_docs/blob/master/ref_guide/qucs_s_reference.tex Here is a TODO list for documentation update:

• Setup a repository containing LaTeX sources of the documentation: https://github.com/ra3xdh/qucs_s_docs/
• Prepare Qucs-S simulation reference guide
• Deprecate repository on the readthedocs and replace links in the Qucs-S GUI.

The documentation writing consumes much more time than writing a code. I have no time to complete this task in the near year. The contribution is highly welcome here. Here are some articles on Qucs-S that could be used as the starting point. Sorry, it is available in Russian only:

• Simulation guide: https://habr.com/ru/articles/789452/
• RF simulation guide: https://habr.com/ru/articles/735508/
• Qucs-S overview: https://habr.com/ru/articles/678526/ and https://habr.com/ru/articles/778666/

[tomhajjar]

I recovered/re-created/updated a number of the schematics in the Help section. There are numerous errors in the transformer section. Changes to ngspice and Qucs-S will require schematics and text to change.

Ask for schematics prior to updating the text. It could save a of of time and frustration...

[ra3xdh]

Ask for schematics prior to updating the text

Thanks. I will request the schematics if necessary.

For convenience of not LaTeX users here is the draft of the new reference guide. The structure of the new manuals differs significant from the readthedocs version.

qucs_s_reference.pdf

[viticleri]

Hi,
Let's see, there is a lot of work to be done in terms of documentation. I've checked some of your articles in Russian (very good, by the way!) and it's really a lot of work to translate them, read them chronologically, take advantage of what's not outdated right now and with that, be able to make a good document updated, which is didactic and clear, which does not create confusion and which at the same time is not boring.

In the end, when you study a subject in depth, the best way to understand it is to work on it and make good documentation that serves to explain to others the subject you have supposedly learned.

[3813127458]

I could join to help writing manual sections using LaTeX.
I just need some guidance how you set up version control and peer review of the manual.

There is a potential solution for online real-time collaborative LaTeX writing:
https://github.com/overleaf/overleaf
https://www.overleaf.com/home-2

In the manual I would like to see also a section about circuit optimization.
QUCS-S does probably not support optimization right now, but I use ASCO for this purpose quite successful with the QUCS-S netlist for ASCO: https://asco.sourceforge.net/

[ra3xdh]

There is a potential solution for online real-time collaborative LaTeX writing:

Yes, I am aware about Overleaf. But I am not sure if overleaf supports Git repository integration. The documentation should be put under version control.

In the manual I would like to see also a section about circuit optimization.

The optimization is currently supported only using Qucsator. Ngspice in principle supports ASCO, but for Qucs-S optimization is possible only if you export netlist and run it from the CLI. The ASCO support for Qucs-S+Ngspice could be added in the future versions.

[3813127458]

Yes, Overleaf supports Git repository integration:

https://www.overleaf.com/learn/how-to/Git_integration
https://www.overleaf.com/learn/how-to/Overleaf_premium_features
https://www.overleaf.com/user/subscription/plans

But is is a "premium feature" not for free. Therefore, I think in our case Overleaf is probably useless.

I did write a section 7 about optimization based on your LaTeX template:
qucs_s_reference.pdf

Here is the related LaTeX source folder:
QUCS-S.zip

To clean up and to prepare for a large document including IEEE references format, I did the following minor changes in your LaTeX template:

1. change \usepackage{hyperref} to

\usepackage[pdftex]{hyperref}
\hypersetup{
	colorlinks=true,
	pdfpagemode=UseNone,
	pdfstartview=FitV,
	linkcolor = black,
	filecolor = black,
	urlcolor = black,
	citecolor = black,
	bookmarksopen,
	bookmarksnumbered,
	bookmarksopenlevel=2,
	pdfmenubar=true,
	pdfwindowui=true
}

2. remove \usepackage{cite} and replace by

\usepackage[backend=biber,style=ieee]{biblatex}
\addbibresource{./references/references.bib}

3. add \usepackage{float}
4. add \usepackage{siunitx}
5. add lstlisting format:

\lstset{
	basicstyle=\ttfamily,
	columns=fullflexible,
	breaklines=true
}

6. add label macros \fig{} etc.

The Qucs-S project of the optimization example section 7 is here:
Example_RLC_Optimization_prj.zip

Regarding LaTeX tools I recommend the following setup:

1. Tex Live: https://www.tug.org/texlive/
   Advantage: same behavior on Windows and Linux platforms. No utf code page issues etc.

2. TeXstudio: https://www.texstudio.org/
   Advantage: same behavior on Windows and Linux platforms. Very nice LaTeX solution:
   Not to forget: the bibliography build setup need to be changed to biber in the settings.

3. Labels, figure filenames and citation references should be an unambiguous string. For large documents with hundred of labels, figures and citation references it does not make sense to write meaningful names. I use a Python script, which posts a label string into the clipboard, based on the UTC timestamp in micro second resolution:

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Created on Sun Feb 25 08:21:54 2024
https://stackoverflow.com/questions/64023578/convert-an-integer-to-an-alphanumeric-string-with-as-few-characters-as-possible
@author: werner
"""

from datetime import datetime, timezone
import pyperclip

BS="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"
def to_base(n, b): 
  if not n: return "0"
  return to_base(n//b, b).lstrip("0") + BS[n%b]

# get current datetime in UTC
utc_dt = datetime.now(timezone.utc)

# convert current datetime in UTC to timestanp integer label
v = int(utc_dt.timestamp()*1e6)

label = to_base(v,len(BS))
# label = str(v)
print(label)

# copy label string into clipboard
pyperclip.copy(label)

Example: GTRDGIRQVW

4. Sometimes it is necessary to crop PDF figures (print Qucs-S schematic to PDF ) to its contents.
   For this purpose I use this Python script:

# -*- coding: utf-8 -*-
"""
Created on Tue Nov 20 18:33:35 2018

@author: ARTP2
"""
# This script uses the path of a PDF file in the clipboard and performs:
# 1: crop the PDF to its content (to remove border)
# 2: export EMF for power point (vector graphics resolution)
# 3: export SVG for Inkscape editing
#
# Prerequisites: Inkscape (for emf and svg export) and TeXLive (for pdfcrop) must be installed

import pyperclip
import subprocess
from pathlib import Path
import sys
import os

# copy file path to clipboard
def path_copy():
    txt = pyperclip.paste()
    if sys.platform == 'linux':
        fpath = txt[txt.find('file://')+7:-1]
        print(txt)
        return txt
    elif sys.platform.startswith('win'):
        print(txt)
        return txt
    else:
        print('Error: no linux or windows OS detected')
        return -1

pf = Path(path_copy())
print(pf)


# crop PDF

cmdCommand = "pdfcrop " + str(pf) + " " + str(pf)
print (cmdCommand)
subprocess.call(cmdCommand, shell=True)
print ('done')

# pop up PDF
if os.name == 'posix':
    cmdCommand = 'okular ' + str(pf.with_suffix('.pdf'))
    subprocess.call(cmdCommand, shell=True)
else:   
    os.startfile(pf.with_suffix('.pdf'))



## PDF to EMF
#cmdCommand = r"C:\PROGRA~1\Inkscape\inkscape.exe -f=" + txt + r" --export-emf=" + head + "\\" + fname[0] + ".emf"
#print(cmdCommand)
#process = subprocess.Popen(cmdCommand.split(), stdout=subprocess.PIPE)
#output, error = process.communicate()
#print(output)
#
## PDF to EMF
#cmdCommand = r"C:\PROGRA~1\Inkscape\inkscape.exe -f=" + txt + r" --export-plain-svg=" + head + "\\" + fname[0] + ".svg"
#print(cmdCommand)
#process = subprocess.Popen(cmdCommand.split(), stdout=subprocess.PIPE)
#output, error = process.communicate()
#print(output)

I am not sure how my proposals are in line with the work flow of your team.
If I should contribute to a Git repository including version control, someone need to guide me how to setup the Git flow.

[ra3xdh]

If I should contribute to a Git repository including version control, someone need to guide me how to setup the Git flow.

The usage of Git is sufficient easy especially on Linux platform. You don't need programming knowledge to use Git. The following instruction is suitable for all repository: https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project

In a short words you should make the following:

• Make fork
• Clone the the LaTeX sources from fork to your hard drive
• Make new branch
• Make changes and commit
• Push changes to your fork
• Open PR
• Delete branch after PR is accepted; update master branch on your local copy

[ra3xdh]

Please follow the following rules while making PRs to documentation:

• Don't put under version control auto-generated files like *.aux
• The putting of the large binary files (>= 1Mb) under version control should be avoided

[paulmcquad]

Hi Everyone,

@ra3xdh @tomhajjar @3813127458 @viticleri

I was wondering would it be better to change to Asciidoctor. Change Latex to Asciidoctor is easier and more organized. it outputs to different formats like pdf, html5 etc.

• See website for more details: https://asciidoctor.org/

P.S. I could help start to process by Forking and adding a PR.

Update: ra3xdh/qucs_s_docs#1

Qucs with SPICE, First Edition
https://github.com/paulmcquad/qucs_s_docs/releases/tag/v0.0.1

[ra3xdh]

@3813127458 I have created an empty Overleaf project for the future documentation: https://www.overleaf.com/project/65ed52fbd51e0623f11e285a You write everything here, and we can synchronize with Github later. Please tell me how can I invite you for editing?

[3813127458]

@ra3xdh: I did create my Overleaf account according your invitation and everything works seamless.
I did upload and compile my LaTeX contribution: a sub-section about optimization.
Probably now you can review the result.

We can say now: yes, Overleaf works.
However, I am not sure if Overleaf is optimum solution. I never used it before.
I know that students use Overleaf to work on larger documents together as a group.
It is a real time system. Everybody can see changes in real time.
Disadvantage: cloud handling latency and uploads.

In general I prefer a fast workflow (in this case: Texlive, Texstudio, Inkscape, Gimp, Python, Octave) on my local computer and to upload my final result just once.

So, if you and the other potential contributors agree, I would continue to set up the Git flow on a Linux platform.

I need to write a git-based script to perform the following steps, which you did mention above:

• Make fork
• Clone the the LaTeX sources from fork to your hard drive
• Make new branch
• Make changes and commit
• Push changes to your fork
• Open PR
• Delete branch after PR is accepted; update master branch on your local copy

In case you have a solution for such kind of script, please post it.

[ra3xdh]

@3813127458

I am not sure if Overleaf is optimum solution.

Overleaf has one big advantage. It may attract non-Git users and Windows users for writing documentation. I prefer offline workflow too, but let's try to use Overleaf for documentation preparation.

[3813127458]

OK I agree, let's go this way.