Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

如何编写教程

如何开始

在写教程之前，先浏览一下您的教程所在页面。如果这个页面没有被占用，那么此页面就会显示为“不存在的维基”页面（non-existent /Tutorials wiki page）。

一旦您打开这个“不存在的维基”页面，您将会被重定向到如下界面：

单击“TutorialIndexTemplate”链接并保存默认的预览模板，您就可以创建一个如下的新页面：

这个页面对创建您的教程非常有用，同时也会显示一个当前教程的列表。 在栈或包的介绍页面的边栏中会创建一个如下的教程链接：

创建一个教程

在新建教程框（Create a new tutorial）中输入您教程的名字并单击“Enter tutorial name”按钮创建一个基于TutorialTemplate的页面（一些关键字前会显示 ! 符号，使用时请去掉它们）：

####################################
##FILL ME IN
####################################
## for a custom note with links:
## !note =
## for the canned note of "This tutorial assumes that you have completed the 
## previous tutorials:" just add the links 
## !note.0.link= 
## descriptive title for the tutorial
## !title =
## multi-line description to be displayed in search 
## !description = 
## the next tutorial description (optional)
## !next =
## links to next tutorial (optional)
## !next.0.link=
## !next.1.link=
## what level user is this tutorial for 
## !level= (BeginnerCategory, IntermediateCategory, AdvancedCategory)
## !keywords =
####################################

!<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

请注意保存您的页面，因为预览按钮（preview）有事不能正常地工作。

填写模板头信息

上面展示的模板是系统自动生成的文档头信息。效果与本教程的开头类似。现在我们来一起看看这些模板是如何工作的。

提醒

“提示”（note）标签可以生成类似于页面顶部的蓝色提醒框，以用来提示用户如何遵循您的教程。

向其中填写的内容将会生成如下效果：

note= 狂拽炫酷吊炸天。

又如，您可以使用下列关键字：

note.0=[[ROS/Tutorials|ROS教程]]
note.1=[[Documentation| ros.org]]

这样就可以为您的教程添加一个标准的前导教程提示：This tutorial assumes that you have completed the previous tutorials:（本教程假设您已经完成且掌握了下列教程的内容：）

请注意，如果您想在您的自定义提示中加入链接，您可以直接在note标签中包含这个链接而不是单独使用 note.0, note.1等标签单独标记链接。如果您错误的使用了note.0, note.1等标签以下提示内容可能会错误的出现在您的链接前："This tutorial assumes that you have completed the previous tutorials:"

标题

“标题”(title)标签可以创建页面开头的标题，同时它也标记了您教程的标题。教程标题将出现在搜索结果中。

!title= 风骚但不失矜持的名字很重要

概述

“概述”（description）标签会在您的页面顶端显示您的教程概述，此概述也会出现在搜索结果中。

description= 我的葵花宝典狂拽炫酷吊炸天，还不快来试试!

效果如下：

后续

“后续”（next）标签用于显示完成您当前教程之后可以继续学习的其他教程。这个标签是可选的，如果空下将不会显示任何内容。

next=练完葵花宝典的亲们还可以看看
next.0.link=[[ROS/Tutorials|ROS教程]]
next.1.link=[[actionlib_tutorials/Tutorials|actionlib教程]]

效果如下：

您也可以这样使用：

next.0.link=[[actionlib_tutorials/Tutorials|Actionlib教程]]

效果如下：

等级

“等级”（level）标签有双重意义,它不但告诉用户您的教程需要他们达到什么水平，而且也是教程搜索引擎的分类标准之一。 BeginnerCategory：初级 IntermediateCategory：中级 AdvancedCategory：高级

level=AdvancedCategory

效果如下：

关键字

“关键字”（keywords）标签可以帮助用户通过关键字找到您的教程。

keywords= 狂拽, 炫酷, 吊炸天

效果如下：

实用宏命令

ROS维基提供了许多有用的宏命令以帮助您更好的完成您的教程。

代码显示框

目前ROS维基支持以下语言的代码提示框：

c++

• 示例:

  • {{{
    #!cplusplus 
    #include <ros/ros.h>
    int main(int argc, char** argv)
    {
      ros::init(argc, argv, "talker");
      ros::NodeHandle n;
    ...
    }}}

  显示效果:

  •    1 #include <ros/ros.h>
       2 int main(int argc, char** argv)
       3 {
       4   ros::init(argc, argv, "talker");
       5   ros::NodeHandle n;
       6 ...
    

latex

• 示例:

  • {{{
    #!latex 
    $$\overline{\overline{J}} \dot{\overline{v}} = -\overline{k}$$
    }}}

  显示效果:

  • latex error! exitcode was 1 (signal 0), transscript follows:
    
    This is pdfTeX, Version 3.14159265-2.6-1.40.19 (TeX Live 2018) (preloaded format=latex)
    
    kpathsea: Running mktexfmt latex.fmt
    mktexfmt: mktexfmt is using the following fmtutil.cnf files (in precedence order):
    mktexfmt:   /usr/share/texlive/texmf-dist/web2c/fmtutil.cnf
    mktexfmt: mktexfmt is using the following fmtutil.cnf file for writing changes:
    mktexfmt:   /usr/share/httpd/.texlive2018/texmf-config/web2c/fmtutil.cnf
    /usr/bin/mktexfmt: mkdir(/usr/share/httpd/.texlive2018/) failed: Permission denied
    I can't find the format file `latex.fmt'!
    

python

• 示例:

  • {{{
    #!python 
    #!/usr/bin/env python
    import roslib; roslib.load_manifest('beginner_tutorials')
    import rospy
    from std_msgs.msg import String
    def talker():
        pub = rospy.Publisher('chatter', String)
        rospy.init_node('talker', anonymous=True)
    ...
    }}}

  显示效果:

  •    1 #!/usr/bin/env python
       2 import roslib; roslib.load_manifest('beginner_tutorials')
       3 import rospy
       4 from std_msgs.msg import String
       5 def talker():
       6     pub = rospy.Publisher('chatter', String)
       7     rospy.init_node('talker', anonymous=True)
       8 ...
    

CodeRef

在您编写教程的过程中，您有时可能会引用到您之前所写的代码块。这时，您可以使用“CodeRef”引用它们。

{{{
#!cplusplus block=blockname
葵花宝典....
不但 高端大气上档次 
而且 狂拽炫酷吊炸天
}}}

你可以使用“CodeRef”宏来引用上面代码块的特定行：

<<CodeRef(blockname,1,2)>>

效果如下：

   1 葵花宝典....
   2 不但 高端大气上档次 

FullSearchWithDescriptionsCS

“FullSearchWithDescriptionsCS”宏可以根据关键字自动生成教程索引和搜索结果。

<<FullSearchWithDescriptionsCS(title:WritingTutorials BeginnerCategory)>>

这条代码用来显示标题为“WritingTutorials”且分类为“BeginnerCategory”的教程的标题及概述。如果将分类改为“AdvancedCategory”，将没有任何显示结果。

IncludeCSTemplate

这个宏将页面顶端的关键字转换为clearsilver变量，这些变量可以被clearsilver模板命令使用。本教程中的关键字被用在TutorialCSHeaderTemplate中

!<<IncludeCSTemplate(TutorialCSHeaderTemplate)>>

嵌入视频

这个宏可以在本维基中添加视频。将您的视频文献上传至Youtube夹并使用这个宏命令指向您的视频路径就可在您的教程中添加视频。

注意: MediaServer宏已停止使用，所以你必须重新上传你的视频。

这个例子演示了一个在wge100_camera文件夹中的视频。

<<Youtube(Q5KC-trrw_o)>>

示例教程

以下列出了一些优秀的教程共您参考（英文）：

• ROS Tutorials

• Driver Tutorials

• actionlib tutorials

  共同建设ROS中文社区，请联系我。ZhiweiChu