Man pages

[lepalom]

We are creating a debian package for pcl and we have found that there are a lot of application without a man page. We are referring to:

/usr/bin/pcl_add_gaussian_noise
/usr/bin/pcl_boundary_estimation
/usr/bin/pcl_cloud_composer
/usr/bin/pcl_cluster_extraction
/usr/bin/pcl_compute_cloud_error
/usr/bin/pcl_compute_hull
/usr/bin/pcl_concatenate_points_pcd
/usr/bin/pcl_convert_pcd_ascii_binary
/usr/bin/pcl_convolve
/usr/bin/pcl_crop_to_hull
/usr/bin/pcl_demean_cloud
/usr/bin/pcl_dinast_grabber
/usr/bin/pcl_elch
/usr/bin/pcl_extract_feature
/usr/bin/pcl_fast_bilateral_filter
/usr/bin/pcl_feature_matching
/usr/bin/pcl_fpfh_estimation
/usr/bin/pcl_gp3_surface
/usr/bin/pcl_ground_based_rgbd_people_detector
/usr/bin/pcl_hdl_grabber
/usr/bin/pcl_hdl_viewer_simple
/usr/bin/pcl_icp
/usr/bin/pcl_icp2d
/usr/bin/pcl_image_grabber_saver
/usr/bin/pcl_image_grabber_viewer
/usr/bin/pcl_linemod_detection
/usr/bin/pcl_lum
/usr/bin/pcl_manual_registration
/usr/bin/pcl_marching_cubes_reconstruction
/usr/bin/pcl_match_linemod_template
/usr/bin/pcl_mesh2pcd
/usr/bin/pcl_mesh_sampling
/usr/bin/pcl_mls_smoothing
/usr/bin/pcl_modeler
/usr/bin/pcl_multiscale_feature_persistence_example
/usr/bin/pcl_ndt2d
/usr/bin/pcl_ndt3d
/usr/bin/pcl_ni_agast
/usr/bin/pcl_ni_linemod
/usr/bin/pcl_ni_susan
/usr/bin/pcl_nn_classification_example
/usr/bin/pcl_normal_estimation
/usr/bin/pcl_obj2vtk
/usr/bin/pcl_obj_rec_ransac_accepted_hypotheses
/usr/bin/pcl_obj_rec_ransac_hash_table
/usr/bin/pcl_obj_rec_ransac_model_opps
/usr/bin/pcl_obj_rec_ransac_orr_octree
/usr/bin/pcl_obj_rec_ransac_orr_octree_zprojection
/usr/bin/pcl_obj_rec_ransac_result
/usr/bin/pcl_obj_rec_ransac_scene_opps
/usr/bin/pcl_octree_viewer
/usr/bin/pcl_oni2pcd
/usr/bin/pcl_oni_viewer
/usr/bin/pcl_openni_3d_concave_hull
/usr/bin/pcl_openni_3d_convex_hull
/usr/bin/pcl_openni_boundary_estimation
/usr/bin/pcl_openni_change_viewer
/usr/bin/pcl_openni_fast_mesh
/usr/bin/pcl_openni_feature_persistence
/usr/bin/pcl_openni_grabber_depth_example
/usr/bin/pcl_openni_grabber_example
/usr/bin/pcl_openni_ii_normal_estimation
/usr/bin/pcl_openni_image
/usr/bin/pcl_openni_mls_smoothing
/usr/bin/pcl_openni_mobile_server
/usr/bin/pcl_openni_octree_compression
/usr/bin/pcl_openni_organized_compression
/usr/bin/pcl_openni_organized_multi_plane_segmentation
/usr/bin/pcl_openni_passthrough
/usr/bin/pcl_openni_pcd_recorder
/usr/bin/pcl_openni_planar_convex_hull
/usr/bin/pcl_openni_planar_segmentation
/usr/bin/pcl_openni_save_image
/usr/bin/pcl_openni_shift_to_depth_conversion
/usr/bin/pcl_openni_tracking
/usr/bin/pcl_openni_uniform_sampling
/usr/bin/pcl_openni_viewer
/usr/bin/pcl_openni_voxel_grid
/usr/bin/pcl_organized_pcd_to_png
/usr/bin/pcl_organized_segmentation_demo
/usr/bin/pcl_outlier_removal
/usr/bin/pcl_outofcore_print
/usr/bin/pcl_outofcore_process
/usr/bin/pcl_passthrough_filter
/usr/bin/pcl_pcd2ply
/usr/bin/pcl_pcd2png
/usr/bin/pcl_pcd2vtk
/usr/bin/pcl_pcd_change_viewpoint
/usr/bin/pcl_pcd_convert_NaN_nan
/usr/bin/pcl_pcd_grabber_viewer
/usr/bin/pcl_pcd_image_viewer
/usr/bin/pcl_pcd_organized_multi_plane_segmentation
/usr/bin/pcl_pcd_select_object_plane
/usr/bin/pcl_pcd_video_player
/usr/bin/pcl_pclzf2pcd
/usr/bin/pcl_plane_projection
/usr/bin/pcl_ply2obj
/usr/bin/pcl_ply2pcd
/usr/bin/pcl_ply2ply
/usr/bin/pcl_ply2raw
/usr/bin/pcl_ply2vtk
/usr/bin/pcl_plyheader
/usr/bin/pcl_png2pcd
/usr/bin/pcl_point_cloud_editor
/usr/bin/pcl_poisson_reconstruction
/usr/bin/pcl_ppf_object_recognition
/usr/bin/pcl_pyramid_surface_matching
/usr/bin/pcl_radius_filter
/usr/bin/pcl_registration_visualizer
/usr/bin/pcl_sac_segmentation_plane
/usr/bin/pcl_spin_estimation
/usr/bin/pcl_statistical_multiscale_interest_region_extraction_example
/usr/bin/pcl_surfel_smoothing_test
/usr/bin/pcl_test_search_speed
/usr/bin/pcl_tiff2pcd
/usr/bin/pcl_timed_trigger_test
/usr/bin/pcl_train_linemod_template
/usr/bin/pcl_transform_from_viewpoint
/usr/bin/pcl_transform_point_cloud
/usr/bin/pcl_uniform_sampling
/usr/bin/pcl_vfh_estimation
/usr/bin/pcl_viewer
/usr/bin/pcl_virtual_scanner
/usr/bin/pcl_voxel_grid
/usr/bin/pcl_voxel_grid_occlusion_estimation
/usr/bin/pcl_vtk2obj
/usr/bin/pcl_vtk2pcd
/usr/bin/pcl_vtk2ply
/usr/bin/pcl_xyz2pcd

in general the documentation is written. For instance:

$/usr/bin/pcl_extract_feature -h 
Syntax is: /usr/bin/pcl_extract_feature input.pcd output.pcd <options>
  where options are:
                     -feature X = the feature descriptor algorithm to be used (default: FPFHEstimation)
                     -n_radius X = use a radius of Xm around each point to determine the neighborhood in normal estimation (default: 0.000000)
                     -n_k X      = use a fixed number of X-nearest neighbors around each point in normal estimation (default: 0.000000)
                     -f_radius X = use a radius of Xm around each point to determine the neighborhood in feature extraction (default: 0.000000)
                     -f_k X      = use a fixed number of X-nearest neighbors around each point in feature extraction(default: 0.000000)

so, this information should be formatted in in troff format to use with man.

[jspricke]

The generated files are here [1], but we need some cmake magic to install them. @thomas-moulard proposed to use [2] as an example. Searching the web, I've found [3-5] as other sources. Still I'm not sure about the best way to do it:

• Should we go with the files from [1], or convert them to troff or some other format for easier maintenance?
• Does anybody know a good example for a CMake project with man pages?

[1] http://anonscm.debian.org/gitweb/?p=debian-science/packages/pcl.git;a=tree;f=debian/manpages [2] https://raw.githubusercontent.com/jrl-umi3218/jrl-cmakemodules/master/man.cmake [3] http://stackoverflow.com/questions/3375341/man-page-generation-packaging-installation-with-cmake [4] http://public.kitware.com/pipermail/cmake-developers/2011-June/001708.html [5] http://www.cmake.org/pipermail/cmake/2010-November/040774.html

[thomas-moulard]

Related: http://serverfault.com/questions/109490/how-do-i-write-man-pages

Among the recommend software, I find ronn particularly interesting: https://github.com/rtomayko/ronn

As PCL is hosted on GitHub it would allow the GitHub users to see easily the man page (or something close) online while being also useful as a man page once installed. It is available through apt on 12.04.

Please note that I didn't check if the generate man pages are acceptable by Debian standards or not. In particular I recommended [2] because as far as I know man pages must be compressed before being installed (otherwise it will generate a lintian error).

[lepalom]

From my experience, about 95% of the man pages are from the pcl tools and applications. In general they are small programs that do something interesting.

I think that something maintainable could be to have the same information in the source code (--help) parameter than the man page. So, the man pages were generated from using help2man.

I generated almost ALL the pages from here, and the most important work was to reformat the output from help2man program, especially tabs controls, and so on.

In this way, only one place to put the information. For example, I noticed from spell errors in the --help output that I solved in the man pages.

I think that have duplicated this information is waste resources without any important profit.

[thomas-moulard]

I didn't know this command, this seems to be an elegant solution! :+1: for help2man.

[stale[bot]]

Marking this as stale due to 30 days of inactivity. It will be closed in 7 days if no further activity occurs.

[kunaltyagi]

If someone is interested in creating a PR about this, I found a project which integrates help2man in cmake: klatexformula fork