User:Suzanne.soy/XternalApps Workbench/Example: Difference between revisions

From FreeCAD Documentation
(Draft of the template page)
 
m (Section on online documentation)
Line 5: Line 5:
{| class="wikitable"
{| class="wikitable"
|-
|-
! Key !! Value !! Remarks
! Key !! Info status !! Value !! Remarks
|-
|-
| Application name || Example ||
| Application name || TODO || Example ||
|-
|-
| Category || ExampleCategory ||
| Category || TODO || ExampleCategory ||
|-
|-
| Subcategory || ExampleSubCategory ||
| Subcategory || TODO || ExampleSubCategory ||
|-
|-
| Subcategory || OtherSubCategory || Include two or more subcategories if needed.
| Subcategory || TODO || OtherSubCategory || Include two or more subcategories if needed.
|-
|-
| Website || https://www.example.com/ ||
| Website || TODO || https://www.example.com/ ||
|-
|-
| Code || https://github.com/kelseyhightower/nocode ||
| Code || TODO || https://github.com/kelseyhightower/nocode ||
|-
|-
| Doc || https://github.com/example/test/wiki ||
| Doc || TODO || https://github.com/example/test/wiki ||
|-
|-
| Downloads || https://www.example.com/downloads || Example
| Downloads || TODO || https://www.example.com/downloads || Example
|-
|-
| Windows® versions || [https://www.example.com/install.exe Installer], [https://www.example.com/portable.exe Portable] || Example
| Windows® versions || TODO || [https://www.example.com/install.exe Installer], [https://www.example.com/portable.exe Portable] || Example
|-
|-
| macos® versions || [https://www.example.com/macos_version.dmg dmg] || Example
| macos® versions || TODO || [https://www.example.com/macos_version.dmg dmg] || Example
|-
|-
| [[Image:Linux.png]] Linux® versions || [[Image:AppImage-logo.png]][https://www.example.com/example.AppImage AppImage]<br/>[https://www.example.com/example.FlatPak FlatPak]<br/>{{incode|sudo add-apt-repository foobar && sudo apt install example}}<br/>[https://search.nixos.org/packages?channel=20.09&query=example nixpkgs: example] || Prefer an official AppImage, add a note if a format is made by a third-party ( for security reasons, e.g. if it is from a user ppa, and therefore made neither by the application authors nor by distro maintainers, it means trusting an unknown party who has little involvement in either projects). If the project must be compiled from source, provide very detailed steps including a Docker® base image or Ubuntu® version. These steps should work on a fresh installation of the OS in a virtual machine.
| [[Image:Linux.png]] Linux® versions || TODO || [[Image:AppImage-logo.png]][https://www.example.com/example.AppImage AppImage]<br/>[https://www.example.com/example.FlatPak FlatPak]<br/>{{incode|sudo add-apt-repository foobar && sudo apt install example}}<br/>[https://search.nixos.org/packages?channel=20.09&query=example nixpkgs: example] || Prefer an official AppImage, add a note if a format is made by a third-party ( for security reasons, e.g. if it is from a user ppa, and therefore made neither by the application authors nor by distro maintainers, it means trusting an unknown party who has little involvement in either projects). If the project must be compiled from source, provide very detailed steps including a Docker® base image or Ubuntu® version. These steps should work on a fresh installation of the OS in a virtual machine.
|-
|-
| FreeBSD® versions || {{incode|pkg install example}} ||
| FreeBSD® versions || TODO || {{incode|pkg install example}} ||
|-
|-
| Haiku® versions || {{incode|pkgman install example}} or [https://www.example.com/haiku_version.hpkg hpkg] ||
| Haiku® versions || TODO || {{incode|pkgman install example}} or [https://www.example.com/haiku_version.hpkg hpkg] ||
|-
|-
| Available on Windows systems || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
| Available on Windows systems || TODO || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
|-
|-
| Available on Linux systems || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
| Available on Linux systems || TODO || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
|-
|-
| Available on macos systems || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
| Available on macos systems || TODO || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
|-
|-
| Available on FreeBSD systems || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
| Available on FreeBSD systems || TODO || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
|-
|-
| Available on Haiku systems || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
| Available on Haiku systems || TODO || Yes/Not yet/No || "No" means "won't be available because it's impossible / undesirable"
|-
|-
| Supported file formats || .AAA application/x-aaa; .BBB image/bbb; .CCC video/x-ccc etc. ||
| Supported file formats || TODO || .AAA application/x-aaa; .BBB image/bbb; .CCC video/x-ccc etc. ||
|-
|-
| Opening a file || {{incode|example-binary myfile.svg}} ||
| Opening a file || TODO || {{incode|example-binary myfile.svg}} ||
|-
|-
| Converting between file formats using the application || {{incode|example-binary myfile.svg --convert --output=myfile.pdf}} ||
| Converting between file formats using the application || TODO || {{incode|example-binary myfile.svg --convert --output=myfile.pdf}} ||
|-
|-
| Producing one of the accepted file formats from FreeCAD data || {{incode|some python code to produce e.g. an SVG file from a FreeCAD Shape) ||
| Producing one of the accepted file formats from FreeCAD data || TODO || {{incode|some python code to produce e.g. an SVG file from a FreeCAD Shape) ||
|-
|-
| Application uses plug-ins or extensions? || Yes/No || Describe the plug-in mechanism in the section below
| Application uses plug-ins or extensions? || TODO || Yes/No || Describe the plug-in mechanism in the section below
|-
|-
|| Does the application offer a scripting framework? || Yes/No || e.g. Script-Fu for The GIMP, or a command-line interface which gives access to most of the application's tools / features
|| Does the application offer a scripting framework? || TODO || Yes/No || e.g. Script-Fu for The GIMP, or a command-line interface which gives access to most of the application's tools / features
|-
|-
| GUI toolkit(s) used || GTK/Qt5/WxWidgets/… ||
| GUI toolkit(s) used || TODO || GTK/Qt5/WxWidgets/… ||
|-
|-
| Application has "online" documentation || Yes/No || "online documentation" is documentation that can be opened directly from the application, e.g. using the "What's this?" feature, and ironically can usually be browsed offline.
| Application has "online" documentation? || TODO || Yes/No || "online documentation" is documentation that can be opened directly from the application, e.g. using the "What's this?" feature, and ironically can usually be browsed offline.
|-
|-
| Application uses plug-ins or extensions? || Yes/No ||
| Application uses plug-ins or extensions? || TODO || Yes/No ||
|-
|-
| License of the application || CC0/MIT/BSD2/BSD3/proprietary… ||
| License of the application || TODO || CC0/MIT/BSD2/BSD3/proprietary… ||
|-
|-
| Is the application known to rely on patents which are not freely usable? || Yes/Clearly No/Unsure ||
| Is the application known to rely on patents which are not freely usable? || TODO || Yes/Clearly No/Unsure ||
|-
|-
| Does the application rely on a database or other data collection? If so, what are the conditions for its use, redistribution, modification etc.? || Yes + conditions/Clearly No/Unsure || e.g. a clipart library or a collection of hatch patterns, or a database with information about electronic components needed to run simulations or place the components on a PCB.
| Does the application rely on a database or other data collection? If so, what are the conditions for its use, redistribution, modification etc.? || TODO || Yes + conditions/Clearly No/Unsure || e.g. a clipart library or a collection of hatch patterns, or a database with information about electronic components needed to run simulations or place the components on a PCB.
|-
|-
| Trademark guidelines for the application || [https://example.com/trademark-guidelines example] ||
| Trademark guidelines for the application || TODO || [https://example.com/trademark-guidelines example] ||
|-
|-
| … || … ||
| … || … ||
Line 95: Line 95:
* Where are scripts stored in the user's configuration files?
* Where are scripts stored in the user's configuration files?
* Which features of the application can / cannot be accessed from a script?
* Which features of the application can / cannot be accessed from a script?
* Is it possible to save and quit from a script?

== Online documentation ==

"online documentation" is documentation that can be opened directly from the application, e.g. using the "What's this?" feature, and ironically can usually be browsed offline.

How to open the online documentation?
Where is the online documentation stored, and in which format?
How is the online documentation built, from what sources (wiki dump, manually edited HTML files, generated by the application on the fly…)?

Revision as of 09:25, 2 February 2021

The contents of this page are released in the public domain using the Creative Commons CC0 license, contrarily to the rest of the wiki. The contributors agree to waive all rights on their modifications to the fullest extent possible.

Rationale: this is a description of the basic usage of an external application, aimed at facilitating implementation of interoperability tools which target this application, this information should not be encumbered in any way.

Key Info status Value Remarks
Application name TODO Example
Category TODO ExampleCategory
Subcategory TODO ExampleSubCategory
Subcategory TODO OtherSubCategory Include two or more subcategories if needed.
Website TODO https://www.example.com/
Code TODO https://github.com/kelseyhightower/nocode
Doc TODO https://github.com/example/test/wiki
Downloads TODO https://www.example.com/downloads Example
Windows® versions TODO Installer, Portable Example
macos® versions TODO dmg Example
Linux® versions TODO AppImage
FlatPak
sudo add-apt-repository foobar && sudo apt install example
nixpkgs: example
Prefer an official AppImage, add a note if a format is made by a third-party ( for security reasons, e.g. if it is from a user ppa, and therefore made neither by the application authors nor by distro maintainers, it means trusting an unknown party who has little involvement in either projects). If the project must be compiled from source, provide very detailed steps including a Docker® base image or Ubuntu® version. These steps should work on a fresh installation of the OS in a virtual machine.
FreeBSD® versions TODO pkg install example
Haiku® versions TODO pkgman install example or hpkg
Available on Windows systems TODO Yes/Not yet/No "No" means "won't be available because it's impossible / undesirable"
Available on Linux systems TODO Yes/Not yet/No "No" means "won't be available because it's impossible / undesirable"
Available on macos systems TODO Yes/Not yet/No "No" means "won't be available because it's impossible / undesirable"
Available on FreeBSD systems TODO Yes/Not yet/No "No" means "won't be available because it's impossible / undesirable"
Available on Haiku systems TODO Yes/Not yet/No "No" means "won't be available because it's impossible / undesirable"
Supported file formats TODO .AAA application/x-aaa; .BBB image/bbb; .CCC video/x-ccc etc.
Opening a file TODO example-binary myfile.svg
Converting between file formats using the application TODO {{{1}}}
Producing one of the accepted file formats from FreeCAD data TODO some python code to produce e.g. an SVG file from a FreeCAD Shape)
Application uses plug-ins or extensions? TODO Yes/No Describe the plug-in mechanism in the section below
Does the application offer a scripting framework? TODO Yes/No e.g. Script-Fu for The GIMP, or a command-line interface which gives access to most of the application's tools / features
GUI toolkit(s) used TODO GTK/Qt5/WxWidgets/…
Application has "online" documentation? TODO Yes/No "online documentation" is documentation that can be opened directly from the application, e.g. using the "What's this?" feature, and ironically can usually be browsed offline.
Application uses plug-ins or extensions? TODO Yes/No
License of the application TODO CC0/MIT/BSD2/BSD3/proprietary…
Is the application known to rely on patents which are not freely usable? TODO Yes/Clearly No/Unsure
Does the application rely on a database or other data collection? If so, what are the conditions for its use, redistribution, modification etc.? TODO Yes + conditions/Clearly No/Unsure e.g. a clipart library or a collection of hatch patterns, or a database with information about electronic components needed to run simulations or place the components on a PCB.
Trademark guidelines for the application TODO example

Plug-ins and extensions

Describe here the plug-in or extension mechanism(s) thoroughly. Go into detail, give minimal but complete reproducible examples (e.g. steps which can be followed in a freshly-installed virtual machine). Include links to any blog posts, forum questions and other documentation which could help understanding how the plug-in system works; include a one-liner describing the external resource.

Open in tab feature on Linux systems

Relevant portion of xwininfo -root -tree -int and xprop which can be used to identify the window.

  • Make a test with the freshly-opened application window
  • Make a test with a window containing an open document
  • Make a test where another, unrelated application is editing a document whose name contains the name of this application (e.g. for info about Inkscape, open a file named "Inkscape.png" in The GIMP or "Inkscape.txt" in a text editor, and copy-paste here enough lines of xwininfo -root -tree -int and xprop to show how to distinguish the two)

Scripting

Describe here the scripting facilities offered by the application. It could be via an embedded programming or via a rich command-line API.

  • Include here links to the API docs
  • Minimal but complete reproducible examples (e.g. steps which can be followed in a freshly-installed virtual machine) on how to access the command-line interface or how to create and execute a script
  • An example script which uses one tool/filter
  • How to run a script from the command-line: in a new instance of the application
  • How to run a script from the command-line: in an existing instance of the application
  • Where are scripts stored in the user's configuration files?
  • Which features of the application can / cannot be accessed from a script?
  • Is it possible to save and quit from a script?

Online documentation

"online documentation" is documentation that can be opened directly from the application, e.g. using the "What's this?" feature, and ironically can usually be browsed offline.

How to open the online documentation? Where is the online documentation stored, and in which format? How is the online documentation built, from what sources (wiki dump, manually edited HTML files, generated by the application on the fly…)?