View source for Toolhub/cs

<languages/>
{{ptag|toolhub}}
{{Toolhub header|active=User manual}}
[[File:Toolhub community logo.svg|{{dirend}}|frameless|100x100px]]
<div lang="en" dir="ltr" class="mw-content-ltr">
'''[https://toolhub.wikimedia.org/ Toolhub]''' is a community managed catalog of software [[Special:MyLanguage/Tools|tools]] used in the Wikimedia movement. Technical volunteers can use Toolhub to document the tools that they create or maintain. All Wikimedians can use Toolhub to search for tools to help with their workflows and to create lists of useful tools to share with others.
</div>
<div style="text-align:center;">{{Clickable button 2|1=<span lang="en" dir="ltr" class="mw-content-ltr">Visit Toolhub</span>|url=https://toolhub.wikimedia.org/|class=mw-ui-progressive}}</div>
{{TOC side}}
<div lang="en" dir="ltr" class="mw-content-ltr">
== What is a "tool"? ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
In Toolhub, "tool" is an inclusive term for software applications which interact with the Wikimedia projects without being fully implemented by [[Special:MyLanguage/MediaWiki|MediaWiki]]. This includes things like [[w:Wikipedia:User scripts|user scripts]], [[mw:Special:MyLanguage/Extension:Gadgets|gadgets]], [[Special:MyLanguage/Bot|bots]], [[mw:Special:MyLanguage/Help:Templates|templates]], [[mw:Special:MyLanguage/Extension:Scribunto/Lua reference manual|lua modules]], [[w:Web application|web applications]], and [[w:Mobile app|mobile apps]]. The catalog is intended to be inclusive rather than exclusive as long as the things it documents are useful for improving workflows and user experiences when interacting with the projects of the Wikimedia movement.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Content license ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Toolinfo.json data and other structured data collected in Toolhub is licensed under the [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons CC0 Dedication] ('''CC0'''). Re-users are encouraged to provide attribution by linking back to Toolhub, but this is not required for license compliance. It is the responsibility of maintainers of externally hosted toolinfo.json data files to ensure that their contributors are aware of the CC0 licensing requirement. Toolinfo data copied from Wikimedia content wikis or other documentation under a non-CC0 license should restrict the copied ''description'' content to 50 words/250 characters to limit claims of potential copyright license obligations, like attribution. The word/character limit ''only applies to copied content'', and original CC0 descriptions may be any length.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== User accounts ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Toolhub uses [[mw:Special:MyLanguage/Help:OAuth|OAuth]] authentication to allow users to login to Toolhub using their Wikimedia wiki user account. No new accounts or passwords are needed.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Adding tools to the catalog ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Tools can be added to the Toolhub catalog by either being read from a registered toolinfo.json file URL or by directly sending data to the Toolhub API.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Hosting your toolinfo.json files as part of a Git repository makes it possible for volunteers to submit pull requests to help keep the core tool information updated.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Publish a toolinfo file and register it with Toolhub's web crawler ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
A toolinfo file is a JSON document conforming to the [[Toolhub/Data model#Toolinfo_schema|toolinfo schema]]. This standard is an extension of the toolinfo specification originally developed by {{U|Husky}} as part of his [[toolforge:hay/directory/|Hay's Directory]] tool.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# Create a JSON file conforming to the schema
# Publish that file on a website
# [https://toolhub.wikimedia.org/add-or-remove-tools?tab=urls Use the Toolhub UI to register the URL] of the file with Toolhub's web crawler
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Toolhub will check each registered toolinfo URL approximately every 60 minutes and update the catalog with changes.
</div>


<div lang="en" dir="ltr" class="mw-content-ltr">
Example toolinfo.json files from real tools:
</div>
* [https://github.com/eggpi/citationhunt/blob/master/static/toolinfo.json CitationHunt toolinfo.json]
* [https://github.com/doguabaris/Adiutor/blob/main/toolinfo.json Adiutor toolinfo.json]

{{Info|1=<span lang="en" dir="ltr" class="mw-content-ltr">Tools hosted on [[wikitech:Portal:Toolforge|Toolforge]] can use [https://toolsadmin.wikimedia.org toolsadmin] to create a toolinfo record which will automatically be imported by Toolhub and Hay's Directory.</span>}}

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use the Toolhub user interface to create and edit a toolinfo record ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The [https://toolhub.wikimedia.org/add-or-remove-tools?tab=tool-create ''Add or remove tools > Create a new tool'' screen in Toolhub] can be used to create a new toolinfo record directly in Toolhub's catalog. Additional information not collected in the toolinfo creation form can be added via subsequent edits using the ''edit tool'' screen for the tool.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use the Toolhub API to create and edit a toolinfo record ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The <bdi lang="zxx"><kbd>POST /api/tools/</kbd></bdi> endpoint of Toolhub's API can be used to create a new toolinfo record directly in Toolhub's catalog. This API is used behind the scenes by the Toolhub user interface. See [https://toolhub.wikimedia.org/api-docs Toolhub's API documentation] for detailed information about the expected inputs and outputs of this API endpoint.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Editing tool info ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Some of the information contained in the toolinfo record is editable by anyone, but some of it can only be edited by owners or admins. Toolhub's [[Toolhub/Data model|data model]] splits tool information into two parts: the '''core tool info''' and its '''annotations''':
</div>
{| class="wikitable"
|'''<span lang="en" dir="ltr" class="mw-content-ltr">Type of metadata</span>'''
|'''<span lang="en" dir="ltr" class="mw-content-ltr">How it is created</span>'''
|'''<span lang="en" dir="ltr" class="mw-content-ltr">Who can change it</span>'''
|'''<span lang="en" dir="ltr" class="mw-content-ltr">Where to make changes</span>'''
|-
|'''<span lang="en" dir="ltr" class="mw-content-ltr">Core tool info</span>'''

<span lang="en" dir="ltr" class="mw-content-ltr">Basic and essential information about the tool.</span>
|<div lang="en" dir="ltr" class="mw-content-ltr">
Created by using API or Toolhub (the UI uses the API on the backend)
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
[https://toolhub.wikimedia.org/search?origin__term=api&ordering=-modified_date&page=1&page_size=12 Examples]
</div> 

<div lang="en" dir="ltr" class="mw-content-ltr">
OR
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
By submitting a toolinfo.json URL to be crawled
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
[https://toolhub.wikimedia.org/search?origin__term=crawler&ordering=-score&page=1&page_size=12 Examples]
</div>
|<div lang="en" dir="ltr" class="mw-content-ltr">
The [[Toolhub/Decision record#Content ownership/modification model|owner]], Administrators and Oversighters
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
OR
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Users who can change (or submit pull requests for) the externally-stored toolinfo.json file
</div>
|<div lang="en" dir="ltr" class="mw-content-ltr">
In the same place the record was created. If the tool record was originally submitted through Toolhub, it can only be edited through Toolhub.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If tool record data is stored externally in toolinfo.json files, it can only be edited there.
</div>
|-
|'''<span lang="en" dir="ltr" class="mw-content-ltr">Community annotations</span>'''

<span lang="en" dir="ltr" class="mw-content-ltr">Additional information about the tool.</span>
|<span lang="en" dir="ltr" class="mw-content-ltr">Toolhub UI, API, or through tools like Toolhunt that use the API</span>
|<span lang="en" dir="ltr" class="mw-content-ltr">Any authenticated user with a Wikimedia account</span>
|<span lang="en" dir="ltr" class="mw-content-ltr">Toolhub UI, API, or through tools like Toolhunt that use the API</span>
|}
<div lang="en" dir="ltr" class="mw-content-ltr">
=== Core tool info ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
All tools in Toolhub have a core tool record containing basic information, such as the tool name and author. Only the owner, Administrators and Oversighters can edit the core tool info in Toolhub. The [[Toolhub/Decision record#Content ownership/modification model|owner]] of a tool's core information is the user who created it within Toolhub (regardless of which method they used to create it).
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
For externally-stored toolinfo records, anyone with permissions to edit the crawled toolinfo file can edit the core tool info.
</div>
{{Tip|1=<span lang="en" dir="ltr" class="mw-content-ltr">See [[Toolhub/Data model#Toolhub field reference]] for a full list of fields and more information about them.</span>}}
<div lang="en" dir="ltr" class="mw-content-ltr">
==== Editing tool URLs ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The URL for a tool is part of the core toolinfo data. This means that it can be submitted as part of a toolinfo.json file or edited through the UI & API by the [[Toolhub/Decision record#Content ownership/modification model|owner]] of the toolinfo record. It cannot currently be edited by the community at large. You will only be able to edit the tool's URL if you are given the choice of selecting "Edit core toolinfo" after clicking the "edit" button. Otherwise you are seeing the form for editing the "annotations" layer of a toolinfo record -- you will not be able to edit the tool's URL.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If you are a tool maintainer and your record has been imported from https://toolsadmin.wikimedia.org, the edit form on toolsadmin displays a checkbox near the bottom of the form labeled "This is a webservice". Check this box to automatically set the toolinfo record's URL. Note that the Toolhub crawler runs once a hour, so changes to toolinfo records made through Toolsadmin take over an hour to show up.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Avoiding duplicate tool records ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If your tool is hosted in [[wikitech:Help:Toolforge|Toolforge]] and you want your toolinfo records maintained outside of toolsadmin.wikimedia.org to be the primary source of info in Toolhub, set the name in the toolinfo record to <code>toolforge-$TOOL_NAME</code> where <code>$TOOL_NAME</code> is the name you type after become to enter the tool's shell on a Toolforge bastion. The name key is the only field in a toolinfo.json record that is considered when deduplicating the dataset. For examples, see [[phab:T293518]].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Community annotations ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
After Toolhub receives a core tool record, volunteers can submit annotations to it. Annotations help make it easier to find tools by supplying additional information. Annotations cannot be stored in toolinfo.json files; they are meant to always be editable by community members.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The annotations fields are:
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* Icon
* Whether a tool is deprecated/experimental/replaced by another tool
* Tool type
* For Wikis
* Audiences
* Content types
* Tasks
* Subject domains
* Available UI languages
* Links: API, end user docs, feedback, privacy policy, bug tracker, translations, developer docs
* Wikidata QID
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Details about fields that are part of the annotations layer are in the API documentation at https://toolhub.wikimedia.org/api-docs#put-/api/tools/-name-/annotations/.
</div>
{{Tip|1=<span lang="en" dir="ltr" class="mw-content-ltr">See [[Toolhub/Data model#Toolhub field reference]] for a full list of fields and more information about them.</span>}}
<div lang="en" dir="ltr" class="mw-content-ltr">
Some annotations mirror fields from the core toolinfo.json specification. Toolhub only displays an annotations field for community editing if the corresponding field in the core record is empty or missing. '''When both the core and annotation data for a given field are populated, Toolhub displays the core data rather than the annotation data.''' This was chosen as a compromise between the conflicting desires for tool maintainers to have ultimate control of their data records, and for the community to be able to improve the documentation for tools.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Searching for tools ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The search screen uses the [https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html Elasticsearch simple query string syntax]:
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* <code>+</code> signifies AND operation
* <code>|</code> signifies OR operation
* <code>-</code> negates a single token
* <code>"</code> wraps a number of tokens to signify a phrase for searching
* <code>*</code> at the end of a term signifies a prefix query
* <code>(</code> and <code>)</code> signify precedence
* <code>~</code>N<!-- N means "integer" here --> after a word signifies edit distance (fuzziness)
* <code>~</code>N<!-- N means "integer" here --> after a phrase signifies slop amount
* Special characters ({{list|<code>+</code>|<code>{{!}}</code>|<code>-</code>|<code>"</code>|<code>*</code>|<code>(</code>|<code>)</code>|<code>~</code>}}) must be escaped with <code>\</code> or in a quoted phrase to be searched for
* Searches are case-insensitive
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The autocomplete feature is designed to help you with relevant suggestions as you type a query.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Create and share lists of tools ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The ''Your lists'' screen can be found from the link in the user menu available to logged-in users. Click on the user icon in the top navigation bar next to the language selector to open the user menu. Here you can create and edit lists of tools and, when you are ready, mark them as public to share with others.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Tools can also be added to (or removed from) an existing or newly created list directly from the menu button on the tool card, as well as from the menu button on the tool info page.
</div>

<span id="Public_and_featured_lists"></span>
== Veřejné a doporučené seznamy ==

Veřejné seznamy lze prohlížet a vyhledávat v nich tak, že v navigační zásuvce vlevo přejdete do sekce ''Zveřejněné seznamy''. Správci mohou veřejné seznamy označit jako doporučené, což umožní jejich zobrazení na vstupní stránce Toolhubu.

<div lang="en" dir="ltr" class="mw-content-ltr">
Lists can be shared by copying the URL of the list from your browser's URL bar or clicking the ''Copy link and share with others'' link on the list's detail screen.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Save your favorite tools to a special list ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Tools can be marked as "favorites" by logged-in users, which means they are saved to a special list only visible to the current user. This list of favorites can be accessed from the user menu in the top-right corner. To mark a tool as a favorite, click on a tool card to reach the tool info page, then click the ''favorite'' button.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== User permission levels ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Anonymous users ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
All read-only actions can be used without authenticating to Toolhub.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Users ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Authenticated users can perform all read-only actions in the same way that anonymous users can. Additionally they can create new toolinfo records, edit toolinfo records that they have previously created, add annotations to tool records created by others, create new lists, and edit lists that they have previously created.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Bureaucrats ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Bureaucrats can change permissions for other users, including themselves. This includes both granting and removing permissions.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Patrollers ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Patrollers are able to review edits to any toolinfo records and either mark them as patrolled or leave them unpatrolled. There is currently no way for a patroller to reject an edit.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Oversighters ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Oversighters are able to hide (oversight/suppress) any edit. Edits which have been previously hidden can be revealed. Oversighters are also able to edit toolinfo records and lists created by other users so that they can revert a change or make a new edit in order to remove problem content.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Administrators ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Administrators have all of the abilities of bureaucrats, patrollers, and oversighters.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Patrolling changes ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Patrollers and administrators can patrol changes. Patrolling rights are granted by bureaucrats or administrators.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
When a change is made to a toolinfo or a tool list record, it can be patrolled from one of three places:
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* From the page history: click on the option "Mark as patrolled" on the logged entry
* From a link to the change itself: click the "Mark as patrolled" link in the change summary information at the top of the page.
* From ''Recent changes'', accessible from the navigation drawer on the left. Here, you can search and filter recent changes by multiple criteria such as record type (tool or list), username and patrolling status.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Changes can only be accepted (patrolled) or left alone. They cannot be rejected or declined.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Changing user permissions ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Administrators and bureaucrats can change permissions for themselves and other users. Permissions can be added or removed. Each individual addition or removal of permission will show in the audit logs. This means that if two permissions are changed there will be two audit log entries, one for each permission.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== To add a permission ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* Go to the "Members" screen.
* Select the user to modify. Use the search filters to find the user.
* Click on the pencil icon after the user's name. A dialog will be displayed showing the current permissions of the user.
* Choose the group to add from the dropdown list.
* Click the "Add" button.
* A notice will appear on the screen noting that the change has been successful.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== To remove a permission ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* Go to the "Members" screen.
* Select the user to modify. Use the search filters to find the user.
* Click on the pencil icon after the user's name. A dialog will be displayed showing the current permissions of the user.
* Identify the permission to be removed. Click on the red trash can button to remove the permission.
* A notice will appear on the screen noting that the change has been successful.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Oversighting ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Oversighting allows hiding an individual edit to a toolinfo record. This might be used for example when a user has mistakenly published their private information. Administrators and oversighters have the permissions needed to hide or reveal an edit.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Revisions that have been oversighted will have the date/time of the revision, the user's name, and the edit summary hidden in the toolinfo record's history view. All oversight actions are recorded in the audit log, including the name of the oversighter.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== To hide a revision ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* Identify the content to be hidden.
* Review the history to identify when that content was first added.
* Ensure that the content to be hidden is no longer visible in the toolinfo record
** If it is still visible, the toolinfo record owner, an administrator, or an oversighter can edit the toolinfo record to remove the problem content.
* From the toolinfo record history, identify all changes that need to be oversighted.
* Click the "hide" link to hide a revision.
* Repeat as required to oversight all relevant edits.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== To show a hidden revision ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
* From the toolinfo record history, identify all changes that need to be revealed.
* Click the "reveal" link to show a revision.
* Repeat as required to reveal all relevant edits.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
== Translation ==
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Language translations on Toolhub just like other projects and tools at Wikimedia Foundation is handled by the [https://translatewiki.net/w/i.php?title=Special:Translate&group=toolhub&language=en&filter=%21translated&action=translate translatewiki.net community].
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Toolhub provides language selection based on [https://github.com/wikimedia/language-data list of known languages] and not on translation completion, and is configured to provide translations based on a list of fallback languages in varying order of relevance, defaulting to English when there is no translation found for the string in either the selected language or other configured fallback languages. For this reason, you will frequently encounter situations where part of the translations in a page are in the selected language, while others parts are in other languages or English. You can help us fix this by volunteering to translate toolhub on [https://translatewiki.net/w/i.php?title=Special:Translate&group=toolhub&language=en&filter=%21translated&action=translate translatewiki.net].
</div>

[[Category:Toolhub{{#translation:}}]]